API keys and scopes

The Ringhum REST API lets your own systems work with your workspace: list calls and transcripts, create assistants, book appointments, manage contacts, place outbound calls and more. Every request is authenticated with an API key that belongs to one workspace. This article covers creating keys and the conventions every endpoint shares. The full endpoint reference is at /docs.

Who can manage keys

The API is available on every plan. What a key can do is still limited by your plan: for example, creating an assistant beyond your plan's limit returns an error.

Create an API key

1. Open Developers in the sidebar.
2. In the API keys card, click Create key.
3. Enter a Key name that says where the key is used, for example "Production server".
4. Under Scopes, tick read, write or both.
5. Click Create key.
6. Copy the key from the green box and store it somewhere safe, such as your server's secret store. Click Done.

Important: The key is shown only once. Ringhum stores only a fingerprint of it, so it cannot be shown again. If you lose it, create a new key and revoke the old one.

Keys start with ck_live_. The API keys table shows each key's name, the first characters of the key, its scopes, when it was last used and whether it is Active or Revoked.

Scopes

Every key can call the endpoints that only read. Endpoints that create, change or delete something need the write scope. Examples are placing a call, sending a message, booking an appointment, or updating an assistant. The reference at /docs marks these endpoints. A key without write gets a 403 error on them.

Give each system the smallest access it needs. A reporting dashboard needs only read.

Revoke a key

1. On Developers, find the key in the API keys table.
2. Click Revoke and confirm.

Requests using the key fail immediately with 401. Revoked keys stay in the list, marked Revoked, so you can see their history. A key cannot be edited: to change its scopes, create a new key and revoke the old one.

Making requests

• Base URL: https://ringhum.com/api/v1
• Authentication: send the key as a Bearer token: Authorization: Bearer ck_live_…
• Format: JSON in and out. Send Content-Type: application/json with a body.
• Times are ISO 8601 in UTC. Phone numbers are E.164, for example +14155550132. Ids are integers.
• Updates use PATCH with only the fields you want to change.
• Every response carries an X-Request-Id header. Include it when you contact support.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

To check which workspace a key belongs to, call GET /me.

Responses and pagination

A single object comes back as {"data": {…}}. Lists that are paginated come back with a meta object:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Use page and per_page to move through the results. per_page defaults to 25 and can be at most 100.

Errors

Every failure has the same shape, with a stable type you can check in your code:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Rate limits

You can make 120 requests per minute. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers. When you go over the limit you get 429 with a Retry-After header giving the seconds to wait.

Tip: Do not poll for call results. Add a webhook for call.ended and Ringhum sends the summary and transcript to you when the call is done. See Webhooks.

Common questions

Is there a machine-readable spec? Yes. The OpenAPI 3.1 description is at /api/v1/openapi.json and needs no key. You can generate a client from it.

Does a key stop working if the person who created it leaves? No. Keys belong to the workspace and keep working until they are revoked. Revoke keys you no longer trust, especially when someone who had access leaves.

Can I use the API from a web page? No. Anyone who opens the page could read the key. Call the API from your server.