Calling the API

Base URL: https://{{HUBTALK_FQDN}} — every path below starts with /v1. Substitute the host your own dashboard runs on for {{HUBTALK_FQDN}} — for example app.hubtalk.ai.
Format: JSON in the request and in the response. Time values are epoch seconds.
Machine-readable schema: GET https://{{HUBTALK_FQDN}}/openapi.json, with an interactive explorer at https://{{HUBTALK_FQDN}}/docs. The schema is authoritative for requests; success responses are published there as untyped objects, so the tables on this page are the response contract.

Authentication

Every /v1 request carries the key:

Authorization: Bearer YOUR_API_KEY

The secret (cfk_ + hex) is issued in the dashboard and shown once (The access key); the platform stores only a SHA-256 hash. A revoked key stops working immediately — the key record is re-read on every request. A key is scoped to the organization it was issued in: anything outside that boundary is indistinguishable from missing (404), never 403.

Failure	Status	`error.type`	`error.code`
missing or malformed `Authorization` header	401	`authentication_error`	`api_key_required`
unknown key	401	`authentication_error`	`api_key_unknown`
revoked key	401	`authentication_error`	`api_key_revoked`
per-key rate limit exceeded	429	`rate_limit_error`	`api_key_rate_limit_exceeded` (`Retry-After: 60`)
privileged-only operation with a regular key	403	`permission_error`	`privileged_key_required`
privileged operation with a key of a non-root organization	403	`permission_error`	`root_org_key_required`

None of the endpoints in this guide require a privileged key. Per-key rate limit. Each key has a sliding 60-second window over all its /v1 requests. The limit is set per key at creation and can be changed later in the dashboard without rotating the secret (it applies from the next request). A key limit of 0 means the platform default — a deployment setting, 60 requests per minute unless the operator changed it; an operator may also disable the limit. This is one of four distinct 429 sources.

One error envelope

All /v1 errors look the same:

{
  "error": {
    "type": "rate_limit_error",
    "code": "dial_queue_full",
    "status": 429,
    "message": "Dial queue is full; retry after the interval in Retry-After"
  }
}

HTTP status	`error.type`
400, 422	`invalid_request_error`
401	`authentication_error`
403	`permission_error`
404	`not_found_error`
409	`conflict_error`
429	`rate_limit_error`
503	`service_unavailable_error`
500, 502	`api_error`

error.code names the exact cause within the type and is always present: when no more specific cause is registered, code equals type. New codes are added over time — handle an unrecognized code by falling back to type + status. Two additive fields appear only on specific campaign refusals and nowhere else: error.blockers on 409 launch_blocked and error.import on 422 calls_rejected / 422 calls_dnc_matched. Every other error carries exactly the four fields above.

Classify the error on error.type + error.status, and the exact cause on error.code. Never match on error.message — it is a human-readable English diagnostic, looked up by code at the API boundary, and not part of the contract. On 422 schema-validation errors (code: "invalid_request") message is an array of field-level issues in FastAPI/pydantic form ({"type", "loc", "msg", "input"}) rather than a string.

Refusals carry their headers through the envelope: Retry-After on 429s is always delivered.

Rate limits and `429`

A 429 comes from four independent sources. All carry error.type: "rate_limit_error" — distinguish them by error.code:

`error.code`	Source	What to do	`Retry-After`
`api_key_rate_limit_exceeded`	sliding 60-second window on all requests made with the key	slow down your overall request rate	yes, always `60`
`dial_queue_full`	the platform’s dial queue is at its depth ceiling; the call was not created	repeat the same request with the same `Idempotency-Key` after the indicated interval	yes (queue estimate, 1–60 s)
`subgroup_concurrency_limit`	the subgroup’s concurrent-call limit is exhausted	wait for active calls to finish; no honest estimate exists, use your own backoff	no (deliberate)
`subgroup_rate_limit`	the subgroup’s per-minute initiation limit is exhausted	wait out the minute window	yes (`60`)

Subgroup limits default to 10 concurrent calls and 30 initiations per minute unless the administrator configured other values; for a trunk used under a grant the effective limit is the smaller of the subgroup’s and the grant’s.

Request map

Campaigns

Method and path	Purpose
`POST /v1/campaigns`	create the campaign, hand over the numbers, and launch — one request
`GET /v1/campaigns`	cursor-paginated list of campaigns (short views)
`GET /v1/campaigns/{id}`	current state of one campaign
`GET /v1/campaigns/{id}/launch-check`	`{blockers, warnings, dnc_screen}` before acting
`POST /v1/campaigns/{id}/launch`	launch a campaign that stayed a draft
`POST /v1/campaigns/{id}/calls`	add a batch of numbers to an existing campaign
`POST /v1/campaigns/{id}/pause`	stop dialing new numbers
`POST /v1/campaigns/{id}/resume`	continue (launch checks run again)
`POST /v1/campaigns/{id}/cancel`	cancel irreversibly
`GET /v1/campaigns/{id}/progress`	contact states, holds, pace, do-not-call and frequency counters

Uploads

Method and path	Purpose
`GET /v1/imports/{import_id}`	the upload summary plus the live or frozen screening
`GET /v1/imports/{import_id}/report?format=csv`	per-row report, `csv` or `xlsx`
`GET /v1/imports/{import_id}/report?only=dnc_match`	only the do-not-call matches, `csv` or `xlsx`

Lines

Method and path	Purpose
`GET /v1/dialing-routes?agent_id=…`	which trunks and subgroups are available to the agent

Individual calls

Method and path	Purpose
`POST /v1/calls/phone`	one outbound call
`POST /v1/calls/web`	web call: a token for a browser or SDK
`GET /v1/calls`	list of calls with filters and a cursor
`GET /v1/calls/{call_id}`	the full call object
`GET /v1/calls/{call_id}/turns`	per-turn latency metrics of a finished call
`POST /v1/calls/{call_id}/end`	end a live call

​Calling the API

​Calling the API

​Authentication

​One error envelope

​Rate limits and 429

​Request map

Calling the API

Calling the API

Authentication

One error envelope

Rate limits and `429`

Request map