REST API

Everything in the SDK goes through this API, and you can call it directly from any language. The endpoints are listed by area in the sidebar.

The reference is built from our OpenAPI document, which you can feed to your own tools.

Base URL

https://api.hcc.run/v1

Authentication

Send an API key as a bearer token:

curl https://api.hcc.run/v1/calls \
  -H "Authorization: Bearer $HCC_API_KEY"

Create keys on the dashboard's API keys page. The key picks the environment: hcc_test_… for test, hcc_live_… for live. Each endpoint shows the Scope it needs. See API keys and scopes.

Place a call

curl https://api.hcc.run/v1/calls \
  -H "Authorization: Bearer $HCC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-42" \
  -d '{
    "from": "+14155550100",
    "to": "+14155550123",
    "flow": "hello"
  }'

Give exactly one of flow, agentId, instructions or repId. See Calls.

Errors

Errors have a stable code and a message for people. Branch on code:

{ "error": { "code": "forbidden", "message": "This API key is missing the numbers:write scope" } }

Every response has a Request-Id header. Include it when you contact us.

Retries

Send an Idempotency-Key on a POST to make it safe to retry. For 24 hours, the same key and body replays the first response, with an Idempotent-Replayed: true header. See Calls from the SDK.

Pagination

Lists take limit (1 to 100, default 20) and cursor, and return the newest first:

{ "data": [], "nextCursor": null }

Pass nextCursor as cursor to get the next page. It's null on the last one.

Webhooks

We sign what we send you with an Hcc-Signature header. See Call webhooks and Event webhooks.