Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Quickstart

Build messaging workflows using one API for your customers, human support team, and agents. Use scoped service keys on your backend and short-lived contact sessions for customer-facing chat.

Available operations

The OpenAPI reference covers connections, contacts and channel identities, conversation creation and status, text and media messages, internal notes, handoffs, uploads, customer sessions, webhook subscriptions and delivery replay, and restricted credential management.

Create an API key

An account administrator opens Settings → Developers, creates an application, and generates an API key. Select only the needed scopes and allowed inboxes, set an optional expiry, and copy the secret into your backend secret store. The secret is shown once. You can revoke it at any time or disable the whole application.
For this walkthrough, grant connections:read, conversations:read, messages:read, and messages:write for an inbox with an existing conversation. New inboxes are not granted automatically. Sandbox is not available yet.
Use your deployed Ruut origin as RUUT_BASE and the generated credential as RUUT_TOKEN. Never put a production key into a browser or mobile client.

Read context and send

Set RUUT_BASE to your Ruut origin and RUUT_TOKEN to the scoped key. Discover opaque connection and conversation IDs from the list endpoints; do not reuse numeric support-app IDs.
curl "$RUUT_BASE/api/v2/connections" -H "Authorization: Bearer $RUUT_TOKEN"
curl "$RUUT_BASE/api/v2/conversations" -H "Authorization: Bearer $RUUT_TOKEN"
Fetch the conversation and pass its owner_version when sending. Every mutation requires a unique Idempotency-Key for that logical action. Reuse the same key and request body after a timeout.
curl -X POST "$RUUT_BASE/api/v2/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $RUUT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: message-send-0001" \
  -d '{"content":[{"type":"text","text":"Hello from Ruut."}],"expected_owner_version":0}'
A successful send returns 202 and a message ID. Poll GET /api/v2/messages/ or subscribe to delivery events for the outcome.

Upload and send media

Grant media:write for uploads and media:read plus messages:write for sending. Upload bytes using multipart form data:
curl -X POST "$RUUT_BASE/api/v2/media" \
  -H "Authorization: Bearer $RUUT_TOKEN" \
  -H "Idempotency-Key: media-upload-0001" \
  -F "[email protected]"
Use the returned media ID in a typed content part, alongside an optional text part:
{
  "content": [
    { "type": "text", "text": "The document is attached." },
    { "type": "file", "media_id": "med_returned_by_upload" }
  ],
  "expected_owner_version": 0
}
Use image, file, audio, or video as appropriate to the uploaded bytes and the connection's capabilities. Uploads are limited to 20 MB; provider-specific limits may be smaller. Media is account/application protected. Download links expire after five minutes; GET the media resource for a fresh link.

Start a conversation

Create a contact with POST /api/v2/contacts, associate a channel address through POST /api/v2/contacts//identities, then POST /api/v2/conversations with contact_id, connection_id, and identity_id. Creating a conversation does not bypass provider reply windows or opt-in rules. Platform user identities must already have been learned from that provider; API and website chat identities can be created by your trusted backend.