Calling the Sonela API

1. What it is, and what it is not

The API is a third way to reach the assistant you already have, beside the widget and the hosted page. It answers from the same manuals and, where your workspace has them, the same records and lookups, unless you set the key to read only chosen manuals, lookups and templates (Integration › API keys › Readings), and it is read-only in the same way: no request can change your data.

• A key decides everything a request may not. Which data source it asks through, whose records it asks about and what language it answers in are fixed on the key. A request carries a message and nothing that could widen any of them.
• We keep no conversation. The words of a question and of an answer are not stored. A conversation is handed back to you as a sealed value, and you send it with the next message (section 4).
• It is for a server. The API answers no browser: it sends no cross-origin allowance, so a page cannot call it, and a key in a page would be a key given away. For a page, use the widget, which carries no secret.
• It has no pictures, no voice and no documents to send. Those belong to a person at a screen. The API takes text and answers in text and tables.

2. Make a key

In the dashboard, open Integration, then API keys, then New key. The API is part of the Growth and Scale plans.

Everyone in your workspace is emailed when a key is made or rotated. If you receive that email and did not expect it, revoke the key.

3. Ask a question

Send the key as a bearer token and the question as JSON. The examples read the key from an environment variable named SONELA_API_KEY.

curl https://api.sonela.ai/api/v1/chat \
  -H "Authorization: Bearer $SONELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What are your opening hours?" }'

The answer:

{
  "reply": "We are open nine to five, Monday to Friday.",
  "answered": true,
  "tables": [],
  "answeredFromRecords": false,
  "answeredFromMemory": false,
  "conversation": {
    "id": "0d5b1c1e-…",
    "state": "CfDJ8…",
    "expiresAtUtc": "2026-10-01T09:30:00Z"
  },
  "quota": { "limit": 5000, "remaining": 4210, "resetsAtUtc": "2026-11-01T00:00:00Z" },
  "receivedAtUtc": "2026-09-30T09:30:00Z"
}

A message is at most 2,000 characters. Any other field in the request is ignored: the key has already decided it.

4. Carry on a conversation

To ask a follow-up, send the state the last answer gave you. Leave it out to start again.

{
  "message": "And on Saturdays?",
  "conversation": "CfDJ8…"
}

• Treat the state as the conversation itself. It holds the conversation's recent words, sealed so that only we can open it and only under the key's own data source and end-tenant. Store it where you would store the conversation, and with the same care.
• It changes with every answer. Always send the newest one.
• It expires. A state is good for 24 hours from the answer that carried it; expiresAtUtc says when.
• A state that does not open is an ordinary outcome. The request answers 400 conversation_invalid. Send the message again without the state, and the conversation starts afresh.

5. Stream the answer

Ask for a stream with one header and the same request answers as server-sent events, so your software can show the answer as it is written.

curl -N https://api.sonela.ai/api/v1/chat \
  -H "Authorization: Bearer $SONELA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "message": "What are your opening hours?" }'

A request that is refused before the answer begins is answered as plain JSON with its status, not as a stream, so check the status and the content type before reading events. Ignore any event this table does not name.

6. Keep your manuals up to date

A key with knowledge.read or knowledge.write reaches the manuals the assistant answers from — the same ones the Manuals screen shows.

curl https://api.sonela.ai/api/v1/documents \
  -H "Authorization: Bearer $SONELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Returns policy", "content": "Goods may be returned within 30 days…" }'

A file takes two requests on purpose. Send it to convert as a form upload in a field named file, read what it became, correct anything the conversion got wrong, and save that text as a manual. Nothing reaches the assistant that nobody has had the chance to read.

curl https://api.sonela.ai/api/v1/documents/convert \
  -H "Authorization: Bearer $SONELA_API_KEY" \
  -F "file=@price-list.xlsx"

A manual written by your website's crawl can be read here and is changed only at the site: a write to one answers 409 sop_managed_by_website. One read from your Google Docs is changed only in the Doc, and a write to it answers 409 sop_managed_by_google_docs. One read from SharePoint or OneDrive is changed only in the file, and a write to it answers 409 sop_managed_by_sharepoint. One holding the latest posts of a Facebook page or Instagram profile you added is changed only on the page, and a write to it answers 409 sop_managed_by_social_page. Each document says which it is in fromWebsite, fromGoogleDocs, fromSharePoint and fromSocialPage. publicAudience says whether your public assistant reads a manual: a new one that names none is read only by the assistant your own people sign in to, an update that names none keeps what the manual had, and one from your website or a social page is always public. A manual you add or change is searchable shortly afterwards; the list's index says where that stands.

7. Add your customers

If each of your customers has a database of their own with the same tables, your sign-up flow can add them as it creates them. Connect one customer's database in the dashboard and approve its schema once: it becomes the template. A key with organisations.write, which holds nothing else, then reaches these doors.

curl https://api.sonela.ai/api/v1/organisations \
  -H "Authorization: Bearer $SONELA_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "endTenantId": "acme", "name": "Acme Ltd",
        "templateDataSourceId": "…",
        "connectionString": "Host=…;Database=acme;Username=sonela_reader;Password=…" }'

endTenantId is the id your voucher endpoint signs for that customer, and {id} in a path is the same id, URL-escaped. A database whose tables, columns or comments differ from the template's is refused with 409 stamp_schema_differs or 409 stamp_notes_differ and a differences list naming the tables; nothing is made, and you connect it in the dashboard instead. A database that belongs to one customer cannot be given to a second: 409 organisation_route_source_owned.

8. Limits

On any 429, wait for as long as Retry-After says before trying again. Software that retries at once spends the next minute's allowance on refusals.

9. When a request is refused

A refusal is JSON with a status, a title, a detail written for a person, and a code written for your software. Branch on the code, never on the words.

10. Rotating and revoking

• Rotate gives the same key a new secret. By default the old secret stops at once. If you cannot deploy the new one at once, give the old one time to overlap — up to 24 hours — and both work until it ends.
• Revoke stops a key at its next request, and ends any old secret a rotation left working. It cannot be undone.
• If a key may have leaked, revoke it first and make a new one after. A rotation with an overlap leaves the leaked secret working for as long as the overlap lasts.
• If you find a Sonela key that is not yours, send it to hello@sonela.ai and we will end it.

11. The checklist

• The key has only the scopes the software needs.
• Its limits are near what the software really uses.
• It lives in a secret store or an environment variable, on a server.
• The software branches on code, and waits on Retry-After.
• It sends the newest conversation state, and starts again on conversation_invalid.
• It treats 401 as final and does not retry it.
• Somebody reads the email that says a key was made.