API access for developers

How do I get an API key?

1. Open Settings and find the API Access section.
2. Create a key: give it a name and pick its scopes - agents:read, agents:write, agents:publish, agents:test, calls:read.
3. Copy the key immediately. It is shown once at creation and never again; only a hash is stored. Keys can be revoked at any time from the same page.

How do I authenticate?

Send the key as a bearer token on every request. The base URL is https://app.workflowhq.co/api/v1.

curl https://app.workflowhq.co/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

What endpoints are available?

• GET /agents - list your agents (paginated with page and limit).
• POST /agents - create an agent. Supports an idempotency key so safe retries never create duplicates.
• GET /agents/{id} - fetch one agent's full configuration.
• PUT /agents/{id} - update the draft: name, voice, systemPrompt, languages, timezone, transfer destinations, agent transfers.
• POST /agents/{id}/publish - publish the draft so live traffic picks it up.
• POST /agents/{id}/test-call - start a test web call for the agent (limited to 5 per hour).
• GET /calls/{id} - fetch a call record: transcript, duration, outcome, analysis, extracted fields.

How do drafts and publishing work over the API?

Exactly like the dashboard: PUT edits the draft, and live phone calls and widgets keep running the last published version until you POST /publish. Every save is versioned, so changes made over the API appear in the agent's version history and can be reverted from the dashboard.

What do errors look like?

Errors return a JSON body of the shape { "error": { "code": "...", "message": "..." } } with a matching HTTP status: 401 for a missing or invalid key, 403 for a key without the required scope, 404 for a resource that doesn't exist in your organization, 422 for validation errors, and 429 when rate-limited.