API introduction

The GetDialed Flows API is a JSON REST API for managing credentials, flow definitions, batches, and executions, and for browsing the public catalog and template library.

Base URLs

Environment	Base URL
Production	`https://api.getdialed.ai/v1`
Local development	`http://localhost:8000`

Every path is composed against that base as {base}/{group}/{resource}. The groups are flows (definitions, templates, schedules, triggers, webhooks, event subscriptions, batches, executions, jobs, variables, dashboard, usage), account (me, api-keys, auth/stream-token) and data (record-sets); catalog, credentials, tenants, platforms and admin are their own roots. Unversioned paths return 404 — the /v1 segment is required. All request and response bodies are JSON. Send Content-Type: application/json on requests with a body.

Conventions

The API follows standard REST semantics:

Method	Used for	Success status
`GET`	Reads	`200`
`POST`	Creates	`201` (resource creates); `200` for actions such as trigger and credential tests
`PUT`	Full-replacement updates — send every field	`200`
`DELETE`	Deletes and cancels	`204`, 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 (/flows/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/v1/flows/definitions \
  -H "X-API-Key: $GETDIALED_API_KEY"

Pagination and filtering

All list endpoints accept the same query parameters:

Parameter	Type	Default	Constraints
`limit`	integer	`50`	min 1, max 50,000
`skip`	integer	`0`	min 0
`status`	string	none	Valid values vary by resource

curl "https://api.getdialed.ai/v1/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:

Resource	Status values
Catalog platforms	`active`, `inactive`, `coming_soon`
Templates	`active`, `draft`, `archived`
Credentials	`active`, `expired`, `revoked`
Definitions	`active`, `draft`, `archived`
Batches	`pending`, `queued`, `scheduled`, `running`, `paused`, `completed`, `partially_failed`, `failed`, `cancelled`
Executions	`pending`, `running`, `completed`, `failed`, `cancelled`

Errors

Errors return a JSON body with a detail field:

Status	Meaning	Example body
`400`	Bad request — invalid operation, e.g. triggering a non-active definition	`{"detail": "Cannot trigger definition with status 'draft'. Only active definitions can be triggered."}`
`401`	Missing or invalid credentials	`{"detail": "Authentication required"}`
`403`	Authenticated but not permitted — e.g. non-admin token on a mutating endpoint	`{"detail": "Admin role required"}`
`404`	Resource doesn’t exist, or belongs to another account	`{"detail": "Definition not found"}`
`409`	Conflict — duplicate resource or invalid state transition	`{"detail": "Can only cancel pending or scheduled batches"}`
`422`	Validation error — malformed request body or invalid expressions	See below
`503`	Service 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.

Route groups

The sidebar mirrors the URL structure: every endpoint lives under one of seven top-level groups, composed as https://api.getdialed.ai/v1/{group}/....

Flows — `/v1/flows`

The workflow product. Everything that defines, triggers, runs, and observes a flow:

Subgroup	What it does
Definitions	Create and manage flow definitions; `POST .../trigger` starts a run
Templates	Browse the public template library (read-only, no auth)
Schedules	Cron schedules that trigger a definition automatically
Triggers	Read-only history of what started each run, and the batches it spawned
Webhooks	Inbound webhook endpoints — create one, receive deliveries at its `receive_url`, rotate its signing secret
Event Subscriptions	Auto-trigger a definition when a platform event fires
Batches	A triggered run’s unit of work — inspect, pace (`PATCH`), pause/resume/requeue, cancel, and stream progress over SSE
Executions	Individual workflow executions inside a batch, with per-step detail and an SSE stream
Jobs & Exports	Account-wide job feed and CSV export of job outcomes
Variables	Versioned account-scope variable sets, addressable from expressions as `{{ account.<set>.<key> }}`
Dashboard & Usage	Aggregate counts for a dashboard and time-bucketed usage analytics

Account — `/v1/account`

Your session and credentials: GET /account/me (who am I, which account), API key CRUD (mint gd_-prefixed keys, list, revoke), and POST /account/auth/stream-token (short-lived token for browser SSE connections).

Data — `/v1/data`

Bulk data ingestion. Record sets are created, filled in chunks, then sealed — a sealed record set is the reference a definition trigger dispatches from.

Catalog — `/v1/catalog`

The public integration catalog (no auth): platforms → services → actions, with each action’s parameter schema. What you browse here is what a definition’s steps can call.

Credentials — `/v1/credentials`

Stored platform secrets, scoped to your account. One credential belongs to a provider tenant and serves every compatible service of that tenant. Test ad-hoc credentials before saving, or test a saved credential in place.

Tenants — `/v1/tenants`

The provider accounts your credentials authenticate to, across every platform, plus the tenants you named yourself. List, read, rename, and retire.

Five9 Domains — `/v1/platforms/five9`

Per-Domain dispatch operations for the Five9 platform: budget headroom, queue depth, usage history, per-credential attribution, upload cost estimates, margin/lane tuning, limit refresh, and Domain-scoped pause/resume.

Admin — `/v1/admin`

Break-glass dispatch controls (admin role required): pause or resume all dispatch account-wide and inspect every hold currently in force.

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.

Overview

Flows — /v1/flows

Account — /v1/account

Data — /v1/data

Catalog — /v1/catalog

Credentials — /v1/credentials

Tenants — /v1/tenants

Five9 Domains — /v1/platforms/five9

Admin — /v1/admin

Base URLs

Conventions

Authentication

Errors

Route groups

Flows — `/v1/flows`

Account — `/v1/account`

Data — `/v1/data`

Catalog — `/v1/catalog`

Credentials — `/v1/credentials`

Tenants — `/v1/tenants`

Five9 Domains — `/v1/platforms/five9`

Admin — `/v1/admin`

Endpoint reference

​Base URLs

​Conventions

​Authentication

​Pagination and filtering

​Errors

​Route groups

​Flows — /v1/flows

​Account — /v1/account

​Data — /v1/data

​Catalog — /v1/catalog

​Credentials — /v1/credentials

​Tenants — /v1/tenants

​Five9 Domains — /v1/platforms/five9

​Admin — /v1/admin

​Endpoint reference

Base URLs

Conventions

Authentication

Pagination and filtering

Errors

Route groups

Flows — `/v1/flows`

Account — `/v1/account`

Data — `/v1/data`

Catalog — `/v1/catalog`

Credentials — `/v1/credentials`

Tenants — `/v1/tenants`

Five9 Domains — `/v1/platforms/five9`

Admin — `/v1/admin`

Endpoint reference