{"openapi":"3.1.0","info":{"title":"Clockwork API","version":"1.0.0","description":"Execution coordination API. Workflows are dependency graphs; Clockwork owns scheduling, the critical path, and handoffs between human / AI / vendor executors."},"servers":[{"url":"https://platform.clockwork-co.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"A legacy ck_live_… key (user-owned, issued by the Clockwork web app), or a cw_live_…/cw_test_… key (organization-owned, issued via /organizations/{id}/api-keys)."}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code"]}}},"paths":{"/runtime/workflows":{"get":{"summary":"List workflows","operationId":"listWorkflows","responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a workflow (optionally instantiate a template)","operationId":"createWorkflow","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"anchorDate":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"templateId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/workflows/{id}":{"get":{"summary":"Get a workflow by id","operationId":"getWorkflow","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a workflow and all of its tasks","operationId":"deleteWorkflow","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/workflows/{id}/schedule":{"get":{"summary":"Query workflow schedule (tasks, CPM state, conflicts)","operationId":"querySchedule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/tasks":{"get":{"summary":"List tasks","operationId":"listTasks","parameters":[{"name":"workflowId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","active","done","blocked"]}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Create a task","operationId":"createTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","durationMinutes","earliestStart"],"properties":{"name":{"type":"string"},"durationMinutes":{"type":"integer"},"earliestStart":{"type":"string","format":"date-time"},"deadline":{"type":"string","format":"date-time"},"assigneePlatformUserId":{"type":"string","format":"uuid"},"templateInstanceId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/tasks/{id}":{"get":{"summary":"Get a task by id","operationId":"getTask","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Partially update a task","operationId":"updateTask","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"durationMinutes":{"type":"integer"},"status":{"type":"string","enum":["pending","active","done","blocked","cancelled"]},"earliestStart":{"type":"string","format":"date-time"},"deadline":{"type":"string","format":"date-time","nullable":true},"bufferAfterMinutes":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["high","medium","low"],"nullable":true}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/tasks/{id}/assign":{"post":{"summary":"Reassign a task to another executor","operationId":"assignTask","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assigneePlatformUserId"],"properties":{"assigneePlatformUserId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/tasks/{id}/complete":{"post":{"summary":"Complete a task (activates dependents)","operationId":"completeTask","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/tasks/{id}/delay":{"post":{"summary":"Delay a task (slip propagates downstream)","operationId":"delayTask","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delayMinutes":{"type":"integer"},"newEarliestStart":{"type":"string","format":"date-time"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/dependencies":{"post":{"summary":"Create a dependency between two tasks","operationId":"createDependency","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromTaskId","toTaskId"],"properties":{"fromTaskId":{"type":"string","format":"uuid"},"toTaskId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["finish_to_start","start_to_start","finish_to_finish","start_to_finish"]},"lagMinutes":{"type":"integer"}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"summary":"List templates","operationId":"listTemplates","responses":{"200":{"description":"OK"}}}},"/management/events/subscriptions":{"get":{"summary":"List event subscriptions","operationId":"listSubscriptions","responses":{"200":{"description":"OK"}}},"post":{"summary":"Subscribe to push events","operationId":"createSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["task_ready","task_completed","task_delayed","conflict_detected","workflow_completed","*"]}}}}}}},"responses":{"201":{"description":"Created"}}}},"/management/events/subscriptions/{id}":{"delete":{"summary":"Deactivate an event subscription","operationId":"deleteSubscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/billing/usage":{"get":{"summary":"Get API usage summary for the caller","operationId":"getBillingUsage","responses":{"200":{"description":"OK"}}}},"/runtime/mcp/execute":{"post":{"summary":"Dispatch an MCP tool call server-side","operationId":"mcpExecute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool","input"],"properties":{"tool":{"type":"string","enum":["create_workflow","instantiate_template","create_task","create_dependency","assign_task","complete_task","delay_task","query_schedule","delete_workflow","list_workflows","list_tasks","list_templates"]},"input":{"type":"object"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/mcp/stream":{"get":{"summary":"Server-Sent Events stream of workflow change events","operationId":"mcpStream","responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}},"/runtime/mcp/callback":{"post":{"summary":"Callback from an AI agent after completing or failing a task","operationId":"mcpCallback","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taskId","status"],"properties":{"taskId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed","failed"]},"result":{}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/webhooks":{"get":{"summary":"List webhook registrations","operationId":"listWebhooks","responses":{"200":{"description":"OK"}}},"post":{"summary":"Register a webhook","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["task_ready","task_completed","task_delayed","conflict_detected","workflow_completed","*"]}}}}}}},"responses":{"201":{"description":"Created"}}}},"/management/webhooks/{id}":{"delete":{"summary":"Delete a webhook registration","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/organizations":{"get":{"summary":"List organizations the caller is a member of","operationId":"listOrganizations","responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations":{"post":{"summary":"Create an organization (caller becomes its owner)","operationId":"createOrganization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runtime/organizations/{id}":{"get":{"summary":"Get an organization by id","operationId":"getOrganization","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations/{id}":{"patch":{"summary":"Update an organization (requires admin role)","operationId":"updateOrganization","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations/{id}/api-keys":{"get":{"summary":"List an organization's API keys (secrets never included)","operationId":"listApiKeys","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an organization-owned API key (requires admin role)","operationId":"createApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","environment"],"properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Created — the raw key is included exactly once, in this response"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations/{id}/api-keys/{keyId}":{"get":{"summary":"Get an API key by id (secret never included)","operationId":"getApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations/{id}/api-keys/{keyId}/revoke":{"post":{"summary":"Revoke an API key immediately (requires admin role)","operationId":"revokeApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management/organizations/{id}/api-keys/{keyId}/rotate":{"post":{"summary":"Rotate an API key (requires admin role): mints a new secret, and expires the old one after an overlap window (default 24h, 0-168h) instead of revoking it immediately","operationId":"rotateApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"overlapHours":{"type":"integer","minimum":0,"maximum":168}}}}}},"responses":{"201":{"description":"Created — the new raw key is included exactly once, in this response"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}