Developers

Public API Beta

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

Quickstart

1
Create a key
Go to Settings → Developer → API keys. Owners and admins can create keys. The full key is shown once.
2
Choose the minimum scopes
A request succeeds only when the key has the exact resource action required by the endpoint.
3
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://usesonny.com/api/v1/contacts?limit=25 \
  --header "Authorization: Bearer sonny_your_key"

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.

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.

Scopes

contacts:read

contacts:write

conversations:read

conversations:write

messages:read

messages:write

webhooks:read

webhooks:write

Resources

Contacts

List, create, read, update, and archive contacts.

Conversations

List and read conversations; change status, priority, or assignee.

Messages

Read message history and add internal notes.

Webhooks

Manage endpoints, subscriptions, tests, deliveries, and retries.

Responses and errors

Collection responses use data plus pagination. Every response includes x-request-id; you may supply a safe request ID and Sonny will echo it. Errors never expose key or database 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.

Related docs

Webhooks

Beta

Receive signed events with delivery history and retries.

Contacts

Manage your contact list with tags, merging, and auto-creation.

The Inbox

Statuses, priorities, assignment, snoozing, and keyboard shortcuts.

Team Management

Invite members, assign roles, and manage permissions.