Skip to main content

Draft Workflow

Endpoints for safely editing assistants without affecting the live version.

POST /api/assistants/{id}/_edit​

Create a draft copy of an assistant for editing.

Authentication: Required (AI seat)

Permission: assistant:write

Response:

{
  "id": "team:sales-assistant-draft",
  "name": "Sales Assistant",
  "editingId": "team:sales-assistant",
  "...": "...other fields..."
}

Side Effects:

  • Creates a new assistant record with editingId pointing to the original
  • Draft assistant inherits all properties from the original

GET /api/assistants/{id}/draft​

Get the draft version of an assistant.

Authentication: Required (AI seat)

Response: Draft assistant object (if exists)

Error: 404 Not Found if no draft exists

POST /api/assistants/{id}/draft/_commit​

Commit draft changes to the live assistant.

Authentication: Required (AI seat)

Permission: assistant:write

Response: Updated live assistant object

Side Effects:

  • Copies all changes from draft to live assistant
  • Deletes the draft assistant
  • Publishes changes immediately

Transaction: Yes

DELETE /api/assistants/{id}/draft​

Discard draft changes.

Authentication: Required (AI seat)

Permission: assistant:write

Response: 204 No Content

Side Effects:

  • Deletes the draft assistant
  • Original assistant remains unchanged

Draft Workflow Example​

1. Create Draft​

POST /api/assistants/team:sales-assistant/_edit

Response: Draft assistant created with ID team:sales-assistant-draft

2. Edit Draft​

PUT /api/assistants/team:sales-assistant-draft
{
  "instructions": "Updated instructions...",
  "suggestions": ["New suggestion"]
}

3. Add Skills to Draft​

POST /api/assistants/team:sales-assistant-draft/skills
{
  "type": "web-search",
  "name": "Web Search"
}

4. Commit or Discard​

Commit Changes:

POST /api/assistants/team:sales-assistant/draft/_commit

Discard Changes:

DELETE /api/assistants/team:sales-assistant/draft

Benefits of Draft Workflow​

  • Safe Editing - Test changes without affecting live assistant
  • Review Process - Allow others to review before publishing
  • Rollback - Easily discard unwanted changes
  • Atomic Updates - All changes applied at once when committed
Best Practice

Always use drafts when making significant changes to assistants that are actively used in production chats.