Skip to content

Orchestrations API Reference

Complete API reference for the Centrali Orchestration Service.

Base URL

https://api.centrali.io/orchestration/api/v1/workspaces/{workspaceSlug}

Authentication

All requests require a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Orchestrations

List Orchestrations

GET /orchestrations

Query Parameters:

Parameter Type Default Description
page number 1 Page number
pageSize number 20 Items per page (max 100)
sort string createdAt Sort field
order string desc Sort order (asc or desc)

Response:

{
  "data": [
    {
      "id": "orch_abc123",
      "slug": "order-processing",
      "name": "Order Processing Workflow",
      "description": "Process new orders",
      "version": 1,
      "isActive": true,
      "trigger": {
        "type": "event-driven",
        "eventType": "record.created",
        "structureSlug": "orders"
      },
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z",
      "createdBy": "user_xyz789",
      "updatedBy": "user_xyz789"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

Get Orchestration

GET /orchestrations/{orchestrationId}

Response:

{
  "id": "orch_abc123",
  "slug": "order-processing",
  "name": "Order Processing Workflow",
  "description": "Process new orders",
  "version": 1,
  "isActive": true,
  "trigger": {
    "type": "event-driven",
    "eventType": "record.created",
    "structureSlug": "orders"
  },
  "steps": [
    {
      "id": "validate",
      "name": "Validate Order",
      "type": "compute",
      "functionId": "func_abc123",
      "timeoutMs": 30000,
      "nextStepId": "process"
    },
    {
      "id": "process",
      "name": "Process Order",
      "type": "compute",
      "functionId": "func_def456"
    }
  ],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z",
  "createdBy": "user_xyz789",
  "updatedBy": "user_xyz789"
}

Create Orchestration

POST /orchestrations

Request Body:

{
  "slug": "order-processing",
  "name": "Order Processing Workflow",
  "description": "Process new orders through validation and fulfillment",
  "trigger": {
    "type": "event-driven",
    "eventType": "record.created",
    "structureSlug": "orders"
  },
  "steps": [
    {
      "id": "validate",
      "name": "Validate Order",
      "type": "compute",
      "functionId": "func_abc123",
      "nextStepId": "check-result"
    },
    {
      "id": "check-result",
      "name": "Check Validation",
      "type": "decision",
      "cases": [
        {
          "conditions": [
            { "path": "steps.validate.output.isValid", "op": "eq", "value": true }
          ],
          "nextStepId": "fulfill"
        }
      ],
      "defaultNextStepId": "reject"
    },
    {
      "id": "fulfill",
      "name": "Fulfill Order",
      "type": "compute",
      "functionId": "func_def456"
    },
    {
      "id": "reject",
      "name": "Reject Order",
      "type": "compute",
      "functionId": "func_ghi789"
    }
  ]
}

Response: 201 Created

{
  "id": "orch_abc123",
  "slug": "order-processing",
  "name": "Order Processing Workflow",
  "version": 1,
  "isActive": true,
  ...
}

Update Orchestration

PUT /orchestrations/{orchestrationId}

Request Body:

{
  "name": "Updated Order Processing",
  "description": "Updated description",
  "isActive": true,
  "trigger": {
    "type": "event-driven",
    "eventType": "record.created",
    "structureSlug": "orders"
  },
  "steps": [...]
}

Response: 200 OK

Delete Orchestration

DELETE /orchestrations/{orchestrationId}

Response: 204 No Content

Runs

List Runs

GET /orchestrations/{orchestrationId}/runs

Query Parameters:

Parameter Type Default Description
page number 1 Page number
pageSize number 20 Items per page
status string - Filter by status

Response:

{
  "data": [
    {
      "id": "run_xyz789",
      "orchestrationId": "orch_abc123",
      "status": "completed",
      "triggerType": "event-driven",
      "triggerMetadata": {
        "eventType": "record.created",
        "recordId": "rec_123"
      },
      "currentStepId": null,
      "startedAt": "2025-01-15T10:00:00Z",
      "completedAt": "2025-01-15T10:00:15Z",
      "hasErrors": false,
      "delayStepCount": 0,
      "correlationId": "corr_abc123"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

Run Status Values:

Status Description
pending Run is queued
running Run is executing
waiting Run is waiting (delay step)
completed Run finished successfully
failed Run failed with error

Get Run Details

GET /orchestrations/{orchestrationId}/runs/{runId}

Response:

{
  "id": "run_xyz789",
  "orchestrationId": "orch_abc123",
  "status": "completed",
  "triggerType": "event-driven",
  "triggerMetadata": {
    "eventType": "record.created",
    "recordId": "rec_123"
  },
  "input": {
    "event": "record_created",
    "workspaceSlug": "my-workspace",
    "recordSlug": "orders",
    "recordId": "rec_123",
    "data": { ... }
  },
  "context": {},
  "stepOutputs": {
    "validate": { "isValid": true },
    "fulfill": { "orderId": "ord_123" }
  },
  "currentStepId": null,
  "executedSteps": ["validate", "check-result", "fulfill"],
  "startedAt": "2025-01-15T10:00:00Z",
  "completedAt": "2025-01-15T10:00:15Z",
  "hasErrors": false,
  "errors": []
}

Trigger Run

Manually trigger an orchestration run.

POST /orchestrations/{orchestrationId}/trigger

Request Body:

{
  "input": {
    "customField": "value",
    "data": { ... }
  }
}

Response: 201 Created

{
  "id": "run_xyz789",
  "orchestrationId": "orch_abc123",
  "status": "pending",
  "triggerType": "manual",
  "startedAt": "2025-01-15T10:00:00Z"
}

Trigger Types

Event-Driven Trigger

{
  "type": "event-driven",
  "eventType": "record.created",
  "structureSlug": "orders"
}
Field Type Required Description
type string Yes "event-driven"
eventType string Yes Event type to listen for
structureSlug string No Filter to specific structure

Supported Event Types: - record.created - record.updated - record.deleted - record.restored - records.bulk_created

Scheduled Trigger

Cron Schedule: 

{
  "type": "scheduled",
  "scheduleType": "cron",
  "cronExpression": "0 9 * * *",
  "timezone": "America/New_York"
}

Interval Schedule: 

{
  "type": "scheduled",
  "scheduleType": "interval",
  "interval": 3600000,
  "timezone": "UTC"
}

One-Time Schedule: 

{
  "type": "scheduled",
  "scheduleType": "once",
  "scheduledAt": "2025-02-01T09:00:00Z",
  "timezone": "UTC"
}

On-Demand Trigger

{
  "type": "on-demand"
}

Requires manual invocation via the trigger endpoint.

HTTP Trigger

{
  "type": "http-trigger",
  "path": "/webhooks/stripe",
  "validateSignature": true
}

Step Types

Compute Step

{
  "id": "step-id",
  "name": "Step Name",
  "type": "compute",
  "functionId": "func_abc123",
  "timeoutMs": 30000,
  "nextStepId": "next-step"
}
Field Type Required Description
id string Yes Unique step identifier
name string No Display name
type string Yes "compute"
functionId string Yes Compute function ID
timeoutMs number No Timeout (default: 300000)
nextStepId string No Next step (null = end)

Decision Step

{
  "id": "check-status",
  "name": "Check Status",
  "type": "decision",
  "cases": [
    {
      "conditions": [
        { "path": "input.status", "op": "eq", "value": "approved" }
      ],
      "nextStepId": "process"
    },
    {
      "conditions": [
        { "path": "input.status", "op": "eq", "value": "rejected" }
      ],
      "nextStepId": "notify-rejection"
    }
  ],
  "defaultNextStepId": "review"
}

Delay Step

{
  "id": "wait",
  "name": "Wait 1 Hour",
  "type": "delay",
  "delayMs": 3600000,
  "nextStepId": "continue"
}

Condition Operators

Operator Description Value Type
eq Equals any
neq Not equals any
gt Greater than number
gte Greater than or equal number
lt Less than number
lte Less than or equal number
in Value in array array
notIn Value not in array array
exists Field exists none
notExists Field does not exist none

Example Conditions:

// Equals
{ "path": "input.status", "op": "eq", "value": "active" }

// Greater than
{ "path": "input.amount", "op": "gt", "value": 100 }

// In array
{ "path": "input.type", "op": "in", "value": ["premium", "enterprise"] }

// Exists
{ "path": "input.email", "op": "exists" }

Path Syntax

Access data in conditions:

Path Description
input.* Trigger payload data
context.* Shared run context
steps.<id>.output.* Step output

Examples: 

input.recordId
input.data.data.status
input.data.before.version
steps.validate.output.isValid
context.retryCount

Error Responses

400 Bad Request

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    { "field": "trigger.eventType", "message": "required" }
  ]
}

404 Not Found

{
  "error": "not_found",
  "message": "Orchestration not found"
}

409 Conflict

{
  "error": "conflict",
  "message": "Orchestration with slug 'order-processing' already exists"
}