Skip to main content
The GetDialed Flows API is a JSON REST API for managing connections, flow definitions, jobs, and executions, and for browsing the public catalog and template library.

​
Base URLs

EnvironmentBase URL
Productionhttps://api.getdialed.ai/flows
Local developmenthttp://localhost:8000
All request and response bodies are JSON. Send Content-Type: application/json on requests with a body.

​
Conventions

The API follows standard REST semantics:
MethodUsed forSuccess status
GETReads200
POSTCreates201 (resource creates); 200 for actions such as trigger and connection tests
PUTFull-replacement updates — send every field200
DELETEDeletes and cancels204, no body

​
Authentication

Tenant-scoped endpoints accept either an X-API-Key header or a Clerk organization JWT in Authorization: Bearer. Catalog (/catalog/*) and template (/templates/*) endpoints are public and need no credentials. See Authentication for both methods, header precedence, and role requirements on mutating endpoints. 
curl https://api.getdialed.ai/flows/definitions \
  -H "X-API-Key: $GETDIALED_API_KEY"

​
Pagination and filtering

All list endpoints accept the same query parameters:
ParameterTypeDefaultConstraints
limitinteger50min 1, max 50,000
skipinteger0min 0
statusstringnoneValid values vary by resource
curl "https://api.getdialed.ai/flows/definitions?status=active&limit=10&skip=0" \
  -H "X-API-Key: $GETDIALED_API_KEY"
Results are returned in insertion order; there is no sort parameter. Valid status values per resource:
ResourceStatus values
Catalog platformsactive, inactive, coming_soon
Templatesactive, draft, archived
Connectionsactive, expired, revoked
Definitionsactive, draft, archived
Jobspending, scheduled, running, completed, partially_failed, failed, cancelled
Executionspending, running, completed, failed, cancelled

​
Errors

Errors return a JSON body with a detail field:
StatusMeaningExample body
400Bad request — invalid operation, e.g. triggering a non-active definition{"detail": "Cannot trigger definition with status 'draft'. Only active definitions can be triggered."}
401Missing or invalid credentials{"detail": "Authentication required"}
403Authenticated but not permitted — e.g. non-admin token on a mutating endpoint{"detail": "Admin role required"}
404Resource doesn’t exist, or belongs to another account{"detail": "Definition not found: def_abc12345"}
409Conflict — duplicate resource or invalid state transition{"detail": "Can only cancel pending or scheduled jobs"}
422Validation error — malformed request body or invalid expressionsSee below
503Service unavailable — workflow start failed; retry{"detail": "Workflow start failed, records cleaned up"}
A 422 takes one of two shapes. Field-level validation failures use the standard list form: 
{
  "detail": [
    {"loc": ["body", "name"], "msg": "Field required", "type": "missing"}
  ]
}
When a definition’s expressions fail validation, the body pinpoints each bad expression instead: 
{
  "detail": {
    "expression_errors": [
      "Invalid expression '{{invalid..path}}' in step 'step_1', task 0, field 'parameters.message'"
    ]
  }
}
404 is returned both when a resource doesn’t exist and when it belongs to a different account — the API never reveals other tenants’ resource IDs.

​
Endpoint reference

The endpoint pages in this tab are generated from the API’s OpenAPI specification, so parameters, schemas, and response shapes always match the running API. New here? Start with the quickstart or build your first flow.