{"openapi":"3.0.0","info":{"title":"Centrali Orchestration Service API","version":"1.0.0","description":"API documentation for the Centrali Orchestration Service - Multi-step workflow orchestration with compute functions, conditional logic, and scheduling."},"servers":[{"url":"https://api.centrali.io/orchestration/ws/{workspaceSlug}/api/v1","description":"Workspace-scoped Orchestration API","variables":{"workspaceSlug":{"default":"demo","description":"The workspace slug"}}}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Orchestration":{"type":"object","properties":{"id":{"type":"string","description":"Unique orchestration ID (xid format)"},"workspaceSlug":{"type":"string"},"slug":{"type":"string","description":"Unique slug within workspace"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"integer"},"status":{"$ref":"#/components/schemas/OrchestrationStatus"},"trigger":{"$ref":"#/components/schemas/Trigger"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/OrchestrationStep"}},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"updatedBy":{"type":"string"}}},"OrchestrationStatus":{"type":"string","enum":["draft","active","paused"],"description":"Orchestration lifecycle status"},"Trigger":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["event-driven","scheduled","on-demand","http-trigger"]},"eventType":{"type":"string","description":"Event type for event-driven triggers"},"structureSlug":{"type":"string","description":"Structure to watch for events"},"scheduleType":{"type":"string","enum":["interval","cron","once"]},"interval":{"type":"integer","description":"Interval in seconds"},"cronExpression":{"type":"string","description":"5-field cron expression"},"scheduledAt":{"type":"string","format":"date-time","description":"ISO datetime for once type"},"timezone":{"type":"string","description":"IANA timezone (default: UTC)"},"path":{"type":"string","description":"Webhook path for http-trigger"},"validateSignature":{"type":"boolean","description":"Enable HMAC signature validation"},"signingSecret":{"type":"string","description":"Secret for HMAC validation"},"signatureHeaderName":{"type":"string","description":"Header containing signature"}}},"OrchestrationStep":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"Unique step ID within orchestration"},"name":{"type":"string"},"type":{"type":"string","enum":["compute","decision","delay"]},"functionId":{"type":"string","format":"uuid","description":"Compute function ID (compute steps)"},"timeoutMs":{"type":"integer","description":"Timeout in milliseconds (compute steps)"},"retry":{"$ref":"#/components/schemas/RetryConfig"},"onSuccess":{"$ref":"#/components/schemas/OnSuccess"},"onFailure":{"$ref":"#/components/schemas/OnFailure"},"cases":{"type":"array","items":{"$ref":"#/components/schemas/DecisionCase"},"description":"Decision cases (decision steps)"},"defaultNextStepId":{"type":"string","description":"Fallback step (decision steps)"},"delayMs":{"type":"integer","description":"Delay duration in ms (delay steps)"},"nextStepId":{"type":"string","description":"Next step ID"}}},"RetryConfig":{"type":"object","properties":{"maxAttempts":{"type":"integer"},"backoffMs":{"type":"integer"}}},"OnSuccess":{"type":"object","properties":{"nextStepId":{"type":"string"}}},"OnFailure":{"type":"object","properties":{"action":{"type":"string","enum":["fail","end"]}}},"DecisionCase":{"type":"object","required":["conditions","nextStepId"],"properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"}},"nextStepId":{"type":"string"}}},"Condition":{"type":"object","required":["path","op"],"properties":{"path":{"type":"string","description":"Dot-notation path (e.g., input.data.status)"},"op":{"type":"string","enum":["eq","neq","gt","gte","lt","lte","in","notIn","exists","notExists"]},"value":{"description":"Value to compare against"},"valuePath":{"type":"string","description":"Dynamic value path"}}},"OrchestrationRun":{"type":"object","properties":{"id":{"type":"string"},"orchestrationId":{"type":"string"},"orchestrationVersion":{"type":"integer"},"workspaceSlug":{"type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"},"currentStepId":{"type":"string"},"input":{"type":"object"},"context":{"type":"object"},"stepOutputs":{"type":"object"},"correlationId":{"type":"string"},"triggerType":{"type":"string","enum":["event-driven","scheduled","on-demand","http-trigger"]},"triggerMetadata":{"$ref":"#/components/schemas/TriggerMetadata"},"hasErrors":{"type":"boolean"},"delayStepCount":{"type":"integer"},"failureReason":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"ttlExpiresAt":{"type":"string","format":"date-time"}}},"RunStatus":{"type":"string","enum":["pending","running","waiting","completed","failed"]},"TriggerMetadata":{"type":"object","properties":{"eventType":{"type":"string"},"scheduleId":{"type":"string"},"initiatedByPrincipalId":{"type":"string"},"webhookPath":{"type":"string"}}},"OrchestrationRunStep":{"type":"object","properties":{"id":{"type":"string"},"orchestrationRunId":{"type":"string"},"stepId":{"type":"string"},"stepType":{"type":"string","enum":["compute","decision","delay"]},"attempt":{"type":"integer"},"status":{"type":"string","enum":["pending","running","waiting","succeeded","failed"]},"input":{"type":"object"},"output":{"type":"object"},"decisionResult":{"$ref":"#/components/schemas/DecisionResult"},"delayConfig":{"$ref":"#/components/schemas/DelayConfig"},"error":{"$ref":"#/components/schemas/StepError"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"executionId":{"type":"string"},"functionRunId":{"type":"string"},"functionId":{"type":"string"}}},"DecisionResult":{"type":"object","properties":{"evaluatedCases":{"type":"integer"},"matchedCaseIndex":{"type":"integer"},"selectedNextStepId":{"type":"string"},"evaluations":{"type":"array","items":{"$ref":"#/components/schemas/CaseEvaluation"}}}},"CaseEvaluation":{"type":"object","properties":{"caseIndex":{"type":"integer"},"nextStepId":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/ConditionEvaluation"}},"matched":{"type":"boolean"}}},"ConditionEvaluation":{"type":"object","properties":{"path":{"type":"string"},"operator":{"type":"string"},"expectedValue":{},"valuePath":{"type":"string"},"actualValue":{},"pathExists":{"type":"boolean"},"matched":{"type":"boolean"},"error":{"type":"string"}}},"DelayConfig":{"type":"object","properties":{"delayMs":{"type":"integer"},"resumeAt":{"type":"string","format":"date-time"},"resumedAt":{"type":"string","format":"date-time"}}},"StepError":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"stack":{"type":"string"}}},"CreateOrchestrationInput":{"type":"object","required":["slug","name","trigger","steps"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"trigger":{"$ref":"#/components/schemas/Trigger"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/OrchestrationStep"}}}},"UpdateOrchestrationInput":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/OrchestrationStatus"},"trigger":{"$ref":"#/components/schemas/Trigger"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/OrchestrationStep"}}}},"TriggerRunInput":{"type":"object","properties":{"input":{"type":"object","description":"Custom input for the orchestration"},"correlationId":{"type":"string","description":"Optional correlation ID for tracking"}}},"TestDecisionInput":{"type":"object","required":["testData"],"properties":{"testData":{"type":"object","description":"Test data to evaluate against decision step"}}},"PaginatedOrchestrations":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Orchestration"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedRuns":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrchestrationRun"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Orchestrations","description":"Orchestration CRUD operations"},{"name":"Runs","description":"Orchestration run management"},{"name":"Testing","description":"Decision step testing"},{"name":"Webhooks","description":"Webhook trigger endpoints"}],"paths":{"/orchestrations":{"get":{"summary":"List orchestrations","description":"Retrieve all orchestrations in the workspace","tags":["Orchestrations"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}},{"name":"sort","in":"query","schema":{"type":"string","default":"createdAt"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"List of orchestrations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedOrchestrations"}}}},"401":{"description":"Unauthorized"}}},"post":{"summary":"Create orchestration","description":"Create a new orchestration workflow","tags":["Orchestrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrchestrationInput"}}}},"responses":{"201":{"description":"Orchestration created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orchestration"}}}},"400":{"description":"Invalid request"},"409":{"description":"Slug already exists"}}}},"/orchestrations/{id}":{"get":{"summary":"Get orchestration","description":"Retrieve an orchestration by ID","tags":["Orchestrations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Orchestration details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orchestration"}}}},"404":{"description":"Orchestration not found"}}},"put":{"summary":"Update orchestration","description":"Update an existing orchestration","tags":["Orchestrations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrchestrationInput"}}}},"responses":{"200":{"description":"Orchestration updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orchestration"}}}},"400":{"description":"Invalid request"},"404":{"description":"Orchestration not found"}}},"delete":{"summary":"Delete orchestration","description":"Delete an orchestration","tags":["Orchestrations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Orchestration deleted"},"404":{"description":"Orchestration not found"}}}},"/orchestrations/{orchestrationId}/runs":{"get":{"summary":"List runs","description":"List all runs for an orchestration","tags":["Runs"],"parameters":[{"name":"orchestrationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","running","waiting","completed","failed"]}}],"responses":{"200":{"description":"List of runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedRuns"}}}}}},"post":{"summary":"Trigger run","description":"Manually trigger an orchestration run","tags":["Runs"],"parameters":[{"name":"orchestrationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerRunInput"}}}},"responses":{"201":{"description":"Run triggered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrchestrationRun"}}}},"404":{"description":"Orchestration not found"}}}},"/orchestrations/{orchestrationId}/runs/{runId}":{"get":{"summary":"Get run","description":"Retrieve run details","tags":["Runs"],"parameters":[{"name":"orchestrationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","schema":{"type":"string","enum":["steps"]},"description":"Include step history"}],"responses":{"200":{"description":"Run details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrchestrationRun"}}}},"404":{"description":"Run not found"}}}},"/orchestrations/{orchestrationId}/runs/{runId}/steps":{"get":{"summary":"Get run steps","description":"Retrieve step execution history for a run","tags":["Runs"],"parameters":[{"name":"orchestrationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Step history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrchestrationRunStep"}}}}}}},"404":{"description":"Run not found"}}}},"/orchestrations/{id}/steps/{stepId}/test-decision":{"post":{"summary":"Test decision step","description":"Test decision step logic with sample data without creating a run","tags":["Testing"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stepId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestDecisionInput"}}}},"responses":{"200":{"description":"Decision evaluation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionResult"}}}},"400":{"description":"Invalid step type (not a decision step)"},"404":{"description":"Orchestration or step not found"}}}},"/orchestrations/{id}/webhook":{"post":{"summary":"Webhook trigger by ID","description":"Trigger orchestration via webhook using orchestration ID","tags":["Webhooks"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook accepted","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"Invalid signature"},"404":{"description":"Orchestration not found"}}}},"/webhooks/{path}":{"post":{"summary":"Webhook trigger by path","description":"Trigger orchestration via webhook using custom path","tags":["Webhooks"],"security":[],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook accepted","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"Invalid signature"},"404":{"description":"No orchestration found for path"}}}}}}