API quick start #

The machine routes of HeySora are served from one base URL:

https://api.heysora.ai

The route families are /api/v1 (the app channel and integration API), /channel/v1 (the generic channel gateway) and /chat/v1 (web chat).

1. Get credentials #

Credentials belong to a connection in your organisation. Sign in to the workspace, open Developers and create a connection. The portal shows the credentials for that connection; keep them on your server and never put them in a mobile app or a web page. Start in the sandbox: it is a separate environment with its own credentials and no real customers.

2. Call the API #

Every server-to-server request carries a bearer token and is signed. The request shape looks like this (the signature headers are described in the authentication article, not repeated here):

curl -X POST "https://api.heysora.ai/api/v1/<route>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

The signing scheme has versions and is documented in one place only: the Help article Authentication and request signing in your workspace (sign-in required). Prefer the official SDKs or follow that article exactly; do not copy signing code from third-party posts.

3. Handle results #

• Responses are JSON. Errors carry a stable machine-readable code.
• Retry only requests that are safe to retry and use idempotency keys where the API provides them.
• Respect rate limits: back off when you receive 429.

Next: Authentication, webhooks, and the full API reference in the workspace.