Workflow Draft and Deploy Lifecycle

Workflow definitions now support an explicit draft and deploy lifecycle. API consumers can stage workflow edits as an active draft, inspect draft state without changing the deployed version, and promote or discard the draft with dedicated endpoints when the change is ready.

What's New

• Workflow create requests are deployed by default, with an opt-in draft mode via isDeployed: false.
• Workflow list and get requests continue to return deployed versions by default.
• includeDraft=true on workflow list and get requests prefers the active draft when present, then falls back to the deployed version.
• Workflow update requests now save or upsert only the active draft.
• New deploy and discard endpoints control when the active draft becomes deployed or is removed.
• Deleting a workflow soft-deletes all active versions for that workflow ID.

New Endpoints

• POST /api/v1/accounts/{accountId}/workflows/{workflowId}/deploy - promotes the active draft to the deployed version.
• DELETE /api/v1/accounts/{accountId}/workflows/{workflowId}/draft - discards only the active draft.

Modified Endpoints

• POST /api/v1/accounts/{accountId}/workflows - creates a deployed workflow by default. Pass isDeployed: false to create the initial version as a draft.
• GET /api/v1/accounts/{accountId}/workflows - returns deployed versions by default. Pass includeDraft=true to prefer active drafts.
• GET /api/v1/accounts/{accountId}/workflows/{workflowId} - returns the deployed version by default. Pass includeDraft=true to prefer the active draft.
• PATCH /api/v1/accounts/{accountId}/workflows/{workflowId} - saves or upserts the active draft only. It does not accept isDeployed and does not deploy.
• DELETE /api/v1/accounts/{accountId}/workflows/{workflowId} - soft-deletes all active deployed and draft versions for the workflow ID.

Create a Draft Workflow

Create requests still deploy immediately unless you explicitly opt into draft mode:

{
  "name": "Daily Revenue Brief",
  "command": "/daily-revenue-brief",
  "description": "Summarize revenue and write a Markdown report.",
  "steps": [
    {
      "id": "query-revenue",
      "name": "Query revenue",
      "order": 0,
      "type": "tool_call",
      "toolName": "run_sql",
      "toolArgs": {
        "query": "SELECT CURRENT_DATE AS report_date, SUM(amount) AS revenue FROM orders WHERE order_date = CURRENT_DATE"
      }
    }
  ],
  "inputs": null,
  "isDeployed": false
}

Read Draft State

Use includeDraft=true when an editor or automation needs to see staged changes:

GET /api/v1/accounts/{accountId}/workflows?includeDraft=true
GET /api/v1/accounts/{accountId}/workflows/{workflowId}?includeDraft=true

Without includeDraft=true, both endpoints return only deployed workflow versions.

Save a Draft

PATCH now saves the active draft. It creates the next draft version when no active draft exists and updates the current draft in place when one is already present:

{
  "description": "Updated revenue brief workflow.",
  "baseVersion": 1
}

Do not send isDeployed to PATCH /api/v1/accounts/{accountId}/workflows/{workflowId}. Deployment is handled separately.

Deploy or Discard a Draft

Promote the active draft when it is ready:

POST /api/v1/accounts/{accountId}/workflows/{workflowId}/deploy

Discard the active draft while leaving the deployed workflow unchanged:

DELETE /api/v1/accounts/{accountId}/workflows/{workflowId}/draft

Migration Notes

• Existing create clients can keep omitting isDeployed; the created workflow remains deployed by default.
• Clients that previously sent isDeployed while updating a workflow should remove that field and call the deploy endpoint after saving the draft.
• Clients that need to edit staged changes should pass includeDraft=true when listing or fetching workflows.
• Clients that only execute or display live workflows should continue using the default list/get behavior, which returns deployed versions only.