Skip to main content

​
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:
PropertyDescription
version_majorPublished version (e.g., 1, 2, 3)
version_minorDraft version (e.g., 1, 2, 3)
is_publishedWhether 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:
  1. Task was at version 1.0 (published)
  2. Your update created version 1.2 (draft)
  3. last_live contains the snapshot of version 1.0
  4. 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:
  1. Draft version 1.2 became published version 2.0
  2. is_published set to true
  3. last_live cleared (no longer needed)
  4. 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:
  1. Draft changes discarded
  2. Reverted to last published state (version 1.0)
  3. All unpublished edits lost

​
Use Cases

​
1. Review Process

Example Workflow:
  1. Developer updates task description (creates draft)
  2. Adds code examples (draft v1.2)
  3. Asks manager to review
  4. Manager approves → publish draft
  5. 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

Don’t leave drafts unpublished for extended periods. This can cause sync issues with collaborators.
Use the draft workflow for significant updates that benefit from review. Skip it for minor changes like status updates.
When publish fails due to conflicts, fetch the latest published version, merge changes manually, and republish.
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:
  1. Fetch latest published version (GET /tasks/{id})
  2. Merge your changes with current state
  3. Create new draft with merged changes
  4. 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