API Reference

Authentication

Every request carries an API key. Keys belong to a workspace, not to a person.

Using your key

Create a key in Settings → API. It is shown once. Send it as a bearer token — never in a query string, and never from a browser.

curl https://api.ringhouse.ai/v1/messages \
  -H "Authorization: Bearer rh_live_xxxxxxxx"

Scopes

Each key is granted scopes when it is created, and they are fixed for its life. A call outside a key's scopes returns 403, never a partial result.

• messages:read, messages:write
• calls:read
• contacts:read
• conversations:read, conversations:write
• numbers:read
• webhooks:write

Rotating scopes means minting a new key.

Rotating a key

Create the replacement first, move your traffic across, then revoke the old one. Revocation takes effect on the next request that presents the key, and only affects that key.

Failures

A missing or malformed key returns 401. A valid key without the right scope returns 403. Neither is retryable — fix the credential rather than backing off.