Draft/Publish Workflow

Overview

Day Copilot implements a draft/publish workflow that allows you to make changes to tasks and events without immediately affecting the published version. This is particularly useful for collaborative editing, review processes, and preventing accidental changes.

The draft/publish workflow is optional. Simple updates (status changes, adding comments) can bypass drafting if needed.

How It Works

Version Numbers

Every task and event has two version numbers:

Property	Description
`version_major`	Published version (e.g., 1, 2, 3)
`version_minor`	Draft version (e.g., 1, 2, 3)
`is_published`	Whether current state is published

Example:

{
  "id": "task-uuid",
  "title": "Complete API documentation",
  "version_major": 2,
  "version_minor": 3,
  "is_published": false
}

This means:

Published version: 2.0 (last accepted state)
Draft version: 2.3 (current working state with 3 edits)
Status: Unpublished (changes not yet live)

State Machine

Creating a Draft

When you update a published task or event, it automatically becomes a draft:

Example: Update Task

PUT /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000
{
  "title": "Complete comprehensive API documentation",
  "priority": "urgent"
}

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete comprehensive API documentation",
    "priority": "urgent",
    "version_major": 1,
    "version_minor": 2,
    "is_published": false,
    "last_live": {
      "title": "Complete API documentation",
      "priority": "high",
      "version": "1.0"
    }
  }
}

What Happened:

Task was at version 1.0 (published)
Your update created version 1.2 (draft)
last_live contains the snapshot of version 1.0
Changes are not yet published

Publishing a Draft

To make your draft changes official, publish the draft:

POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/draft
{
  "action": "accept"
}

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete comprehensive API documentation",
    "priority": "urgent",
    "version_major": 2,
    "version_minor": 0,
    "is_published": true,
    "last_live": null
  }
}

What Happened:

Draft version 1.2 became published version 2.0
is_published set to true
last_live cleared (no longer needed)
Ready for new edits

Discarding a Draft

To revert to the last published version:

POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/draft
{
  "action": "discard"
}

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete API documentation",
    "priority": "high",
    "version_major": 1,
    "version_minor": 0,
    "is_published": true,
    "last_live": null
  }
}

What Happened:

Draft changes discarded
Reverted to last published state (version 1.0)
All unpublished edits lost

Use Cases

1. Review Process

Example Workflow:

Developer updates task description (creates draft)
Adds code examples (draft v1.2)
Asks manager to review
Manager approves → publish draft
OR manager rejects → discard draft

2. Batch Editing

Make multiple changes without notifying collaborators until ready:

// Make several changes
await updateTask(taskId, { priority: 'high' });      // Draft v1.1
await updateTask(taskId, { due_date: tomorrow });    // Draft v1.2
await updateTask(taskId, { description: '...' });    // Draft v1.3

// Publish all at once
await publishDraft(taskId);  // All changes go live as v2.0

3. Conflict Prevention

Two users editing the same task:

When multiple users create drafts, only one can be published. The second will receive a conflict error and must rebase their changes.

Bypassing the Draft Workflow

Some operations don’t require drafting:

Status Changes

POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/complete

This directly publishes the status change without creating a draft.

Adding Comments

POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/comments
{
  "message": "Great progress!"
}

Comments are always immediately visible, no drafting.

Quick Updates

Include publish: true in update requests:

PUT /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000
{
  "priority": "urgent",
  "publish": true
}

This creates and immediately publishes the draft in one operation.

Querying Drafts

Get Only Published Items

GET /api/v1/tasks?published=true

Get Only Drafts

GET /api/v1/tasks?published=false

Include Draft Status

GET /api/v1/tasks?include_draft_status=true

Response includes draft information:

{
  "data": [
    {
      "id": "task-1",
      "is_published": true,
      "version_major": 3,
      "version_minor": 0
    },
    {
      "id": "task-2",
      "is_published": false,
      "version_major": 1,
      "version_minor": 2,
      "has_unpublished_changes": true
    }
  ]
}

Version History

Access previous versions:

GET /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/history

Response:

{
  "data": {
    "current": {
      "version": "2.3",
      "is_published": false,
      "updated_at": "2025-11-02T15:00:00Z"
    },
    "published": {
      "version": "2.0",
      "updated_at": "2025-11-01T10:00:00Z",
      "snapshot": { ... }
    },
    "history": [
      {
        "version": "1.0",
        "published_at": "2025-10-15T12:00:00Z"
      }
    ]
  }
}

Best Practices

Publish Frequently

Don’t leave drafts unpublished for extended periods. This can cause sync issues with collaborators.

Use Drafts for Major Changes

Use the draft workflow for significant updates that benefit from review. Skip it for minor changes like status updates.

Handle Conflicts Gracefully

When publish fails due to conflicts, fetch the latest published version, merge changes manually, and republish.

Communicate Draft Status

In UI, clearly indicate when viewing a draft vs published version to avoid confusion.

Error Handling

Conflict Error

{
  "error": "Draft conflict",
  "message": "Another draft was published while yours was being edited",
  "status": 409,
  "data": {
    "your_version": "1.2",
    "current_version": "2.0",
    "conflicting_fields": ["title", "priority"]
  }
}

Resolution:

Fetch latest published version (GET /tasks/{id})
Merge your changes with current state
Create new draft with merged changes
Publish

Next Steps

Managing Tasks Guide

See draft workflow in action

Tasks & Events Model

Understand the data model

API Reference

Explore draft endpoints

Error Handling Guide

Handle conflicts and errors

Getting Started

Core Concepts

Guides

Resources

Draft/Publish Workflow

Overview

How It Works

Version Numbers

State Machine

Creating a Draft

Example: Update Task

Publishing a Draft

Discarding a Draft

Use Cases

1. Review Process

2. Batch Editing

3. Conflict Prevention

Bypassing the Draft Workflow

Status Changes

Adding Comments

Quick Updates

Querying Drafts

Get Only Published Items

Get Only Drafts

Include Draft Status

Version History

Best Practices

Error Handling

Conflict Error

Next Steps

Managing Tasks Guide

Tasks & Events Model

API Reference

Error Handling Guide

​Overview

​How It Works

​Version Numbers

​State Machine

​Creating a Draft

​Example: Update Task

​Publishing a Draft

​Discarding a Draft

​Use Cases

​1. Review Process

​2. Batch Editing

​3. Conflict Prevention

​Bypassing the Draft Workflow

​Status Changes

​Adding Comments

​Quick Updates

​Querying Drafts

​Get Only Published Items

​Get Only Drafts

​Include Draft Status

​Version History

​Best Practices

​Error Handling

​Conflict Error

​Next Steps

Managing Tasks Guide

Tasks & Events Model

API Reference

Error Handling Guide

Overview

How It Works

Version Numbers

State Machine

Creating a Draft

Example: Update Task

Publishing a Draft

Discarding a Draft

Use Cases

1. Review Process

2. Batch Editing

3. Conflict Prevention

Bypassing the Draft Workflow

Status Changes

Adding Comments

Quick Updates

Querying Drafts

Get Only Published Items

Get Only Drafts

Include Draft Status

Version History

Best Practices

Error Handling

Conflict Error

Next Steps