Sonny
Sign inStart free trial

Developers

Public API Beta

Build workspace integrations with secure, scoped API keys and a stable versioned JSON contract.

Open interactive API reference

Quickstart

  1. 01

    Open API keys

    Open Settings, select Developer, find API keys, then select Create key. Owners and admins can create keys.

  2. 02

    Create API key

    Enter a Name, choose Expires in days, choose Channel access as All channels or Selected channels, and choose the minimum scopes your integration needs under Scopes. A request succeeds only when the key has the exact resource action required by the endpoint. Select Create key.

  3. 03

    Save your API key

    The full key is shown once. Copy it into your secret manager, then select I saved it.

  4. 04

    Send the key

    Use a Bearer token, or send the same value in x-api-key. Never put keys in query strings or browser code.

cURL

curl https://www.usesonny.com/api/v1/contacts?limit=25 \
  --header "Authorization: Bearer sonny_your_key"

Keys stay secure

Key security
Keys use a sonny_ prefix, 64 random characters, one-way hashing at rest, configurable expiry, and a 600 requests/minute per-key limit. A key is bound to one workspace.
To revoke one, select the trash button beside it. Confirm Revoke API key? by selecting Delete. This immediately stops the key.
Authorization on every call
Sonny verifies the hash and scope, then re-checks the creator's active workspace membership, role, and billing state. Removing or deactivating that user immediately disables their keys.
Selected channels are enforced for every REST API and MCP call. Contact access and webhook management are workspace-wide, so those scopes are only available with access to all channels.

Scopes

  • contacts:read
  • contacts:write
  • conversations:read
  • conversations:write
  • messages:read
  • messages:write
  • messages:send
  • webhooks:read
  • webhooks:write
  • kb:read
  • kb:write

Resources

Contacts
List, create, read, update, and archive contacts.
Sources
Discover configured sources and whether each supports chat, email, or both.
Conversations
List and read conversations; change status, priority, or assignee.
Messages
Read message history, add internal notes, and send replies to customers.
Webhooks
Manage endpoints, subscriptions, tests, deliveries, and retries.

Using Sonny from an AI tool

Sonny MCP exposes every public API operation as a tool. Clients connect by signing in with OAuth 2.1 — or with a scoped API key — and every call keeps the same scopes, workspace boundaries, and business rules.

Read the Sonny MCP guide

Responses and errors

Collection responses use data and include pagination where applicable. Every response includes x-request-id; you may supply a safe request ID and Sonny will echo it. Errors return a safe message without exposing sensitive implementation details.

{
  "error": {
    "type": "validation_error",
    "message": "Invalid email address",
    "requestId": "req_01J..."
  }
}
400
Invalid input, JSON, query, or cursor.
401
Missing, invalid, expired, or unscoped API key.
402
The workspace billing state blocks this request.
403
The key creator's workspace role is not allowed.
404
The resource does not exist in the key's workspace.
409
The request conflicts with an existing resource.
429
The per-key rate limit was exceeded.
500
An unexpected error occurred. Retry with the request ID.
503
Webhook delivery backlog is saturated. Retry later.

Rate limits

Each API key may make up to 600 requests per minute. Every response reports the current window through the standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers, so clients can self-throttle instead of guessing. When the limit is exceeded, the API returns 429 with a Retry-After header — wait that many seconds before retrying.

Versioning and deprecation

The API is versioned in the URL path (/api/v1). Within a version we only make additive changes — new endpoints, new optional fields, new enum values. Breaking changes ship as a new version, and before any v1 endpoint is retired we give at least six months' notice: on this page, by email to workspace owners with active API keys, and via Deprecation and Sunset headers on affected endpoints.

Related docs