{ "openapi": "3.1.0", "info": { "title": "SlyOS Developer API", "version": "v1", "description": "Turn any inbox you own — a helpdesk, a ticketing system, your own app’s chat — into a SlyOS channel. Send messages in; SlyOS writes the replies with the account’s own Brain: what the business has taught it, the voice it has learned, and the conversation so far. You send each reply through your own system.\n\n## Authentication\nEvery request sends `Authorization: Bearer `. Keys starting `sly_test_` are the sandbox: free, and they reach nobody. Keys starting `sly_live_` are live. A sandbox key creates and lists sandbox channels; a live key, live ones — and neither can reach the other's messages, cards or replies: an id from the other environment is a `404`. Sandbox drafts are free and limited to 50 in any 24 hours. Each operation names the scope its key must carry, and a key without it is refused `403 missing_scope`. A missing, malformed or revoked key is refused `401 unauthorized`, always with the same sentence.\n\n## What costs money\nOnly `POST /v1/developer/drafts`, only on a live key, and only when a reply is produced:\n- From 2026-09-01: 10¢ per AI response (price version `2026-09-01`)\n\nTaking messages in, reading replies back, reporting deliveries, usage and wallet lookups are free. So is everything in the sandbox. A reply that is refused, fails, or is judged unnecessary is not charged.\n\n## Retrying safely\n- `POST /v1/developer/messages`: the same `external_message_id` on the same channel is stored once; the repeat answers `200` with `duplicate: true`.\n- `POST /v1/developer/drafts`: `generation_id` is the idempotency key for the charge, and it is yours: unique within your account and the key’s environment. Derive it from the `message_id` SlyOS returned — `:reply-1` — so it is unique and the same on a retry. Repeating a `generation_id` that already has a reply gets that reply back with `200` and `replayed: true`, charged nothing (`billed_cents: 0`; on a live key, `already_charged: true`). While the first request is still being drafted, the repeat answers `409 generation_in_progress` with `Retry-After`: retry with the same id. The same id sent for a different conversation is refused `409 generation_id_conflict`, never answered with the first conversation’s reply.\n- `POST /v1/developer/deliveries`: send your own `external_message_id`, and a repeated report is one message.\n\n## Teach SlyOS your business\nA reply is only as good as what SlyOS knows about the business it speaks for. Before the first one, hand it the material your answers must agree with — every reply is then given your rules and the passages nearest the message, and written in the voice SlyOS has learned for the account:\n- **Links and whole sites.** `POST /v1/developer/knowledge/sources` with `{\"url\": \"…\"}` reads one page — your pricing, your policies, a regulation your answers must respect. Add `\"crawl\": true` to read the whole site.\n- **Files.** The same call as `multipart/form-data`, with the file in a `file` field: PDF, Word, plain text, Markdown or CSV. It is read to the end.\n- **Rules.** `\"rules\": true` (a `rules=true` form field, for a file) marks a source replies must follow rather than draw on: terms, a returns policy, a regulation. Every reply carries the rules whole while they fit in one reply; past that, each reply gets the rules nearest its message, and the source says `rules_fit: false`.\n- **Who you are.** `PUT /v1/developer/knowledge/profile` says what the business is and how it wants to sound.\nSources are read in the background: `status` goes `queued`, `processing`, then `ready` — or `failed`, with `status_reason` saying why. A web page is read without running its scripts, so a page that builds its content with JavaScript (prices drawn from a script, a template filled in after it loads) can be missing what a visitor sees: the source is then `ready` with a `warning` naming those pages in `incomplete_pages` — add that text as a file, or as a single link to a page that shows it. Adding and changing them needs a **live** key carrying `brain:write` — sandbox and live replies share them, so a sandbox key may only read them; listing them, `brain:read`. `GET /v1/developer/knowledge/sources/{sourceId}/passages` shows exactly what was read.\nReplies use what you add, the conversation they answer and that customer’s earlier ones — never another customer’s, and never a sandbox conversation in a live reply. They also use everything SlyOS knows about the account owner: facts from their own conversations and the ones they told it, their past replies on their other channels, their documents, calendar and saved details, and their About you. The owner can turn that off on the Developer screen (`use_personal_context`); a key cannot change it. Off, a reply still uses the owner’s name, rules and writing style. Sources added with a key belong to its project unless the request sends `\"scope\": \"account\"`.\n**When sources disagree.** Each reply is given the passages nearest the message. The closest always goes in. The best passage of each other source about as relevant goes in ahead of the rest, in up to half of what a reply carries, so a long website cannot crowd out a short policy; after that, no one source takes more than half while another has something about as relevant. Where two disagree, the reply follows the higher one — rules, then uploaded files, then single links, then pages read from a whole site — and never contradicts the business’s own documents. That order settles disagreements only: a reply answers from the passage that answers the question, and says what another organisation’s page says as theirs.\nEvery reply then says what it relied on: `sources`, on the `POST /v1/developer/drafts` answer and on `GET /v1/developer/drafts/{draftId}`, lists the passages it was given — rules first — with the source, the page range or section, an excerpt of the passage’s own text, and a SHA-256 of the stored passage (with `carried_chars` when only its start fit).\n\n## Held replies\nA reply with `held_for_review: true` was held by SlyOS’s checks for a person to read first — money, health or dosing, a legal or data-protection matter, another sensitive subject, or something the reply gives out that the account has not sent before — and `hold_reasons` says which. Do not send it automatically. `null` means SlyOS can no longer say, and is held; so is a missing field. Every answer that carries a reply carries the hold: the first `POST /v1/developer/drafts` answer, a replay of it, `GET /v1/developer/drafts/{draftId}`, and the `draft.ready` webhook.\n\n## Errors\nEvery refusal has one shape, whatever the status: `{ \"code\": \"…\", \"message\": \"…\" }`. Branch on `code`; show `message` to a person. A `402 insufficient_funds` also carries `available_cents` and `needed_cents`; a `429 sandbox_daily_limit` carries `used_today` and `daily_limit`. Each operation lists its codes under the status it answers them with.\n- `400` — the request is malformed. Fix it; retrying the same request will not help.\n- `401` — the key is not valid. `403` — the key is valid but lacks the scope.\n- `402` — out of API credit. Not an outage: the message is stored and can be answered by hand.\n- `404` — no such object for this key.\n- `409` — a settled state, not a fault (for example, somebody asked whether they are talking to a person). Do not retry — except `generation_in_progress`, `not_stored`, which the operations that answer them say are safe to retry with the same request.\n- `429` — over the rate limit, on an operation that lists `rate_limited`. Wait and retry.\n- `503` — SlyOS cannot reach a model provider. Retry with backoff; nothing was charged.\n\n## Limits\nEach operation states its rate limit in requests a minute; one that lists `429 rate_limited` refuses past it. A message body is at most 32,000 characters.\n\n## Webhooks\nSlyOS can post events to an endpoint the account owner sets on the Developer screen — one for sandbox and one for live, each with its own signing secret; a live endpoint must be HTTPS (see **webhooks**). Every delivery is signed in the `SlyOS-Signature` header; verify it before trusting the body. Delivery is at least once: an endpoint that does not answer `2xx` within ten seconds is tried again, up to 8 attempts over about 62 minutes, under the same event `id` — deduplicate on it. A redirect is not followed: it counts as a failed attempt.\n\n## Versioning\nThe version is in the path (`/v1`). Within a version, responses may gain fields: ignore fields you do not recognise.\n\nThis document is generated from the schemas the server validates with. The same content, readable: https://slyos.world/docs/api." }, "servers": [ { "url": "https://api.slyos.world", "description": "Production. Sandbox and live share this host; the key decides which one a call is." } ], "externalDocs": { "description": "Quickstart", "url": "https://slyos.world/docs/developer-api" }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Messages" }, { "name": "Drafts" }, { "name": "Deliveries" }, { "name": "Usage" }, { "name": "Wallet" }, { "name": "Channels" }, { "name": "Knowledge" }, { "name": "Webhooks" } ], "paths": { "/v1/developer/messages": { "post": { "operationId": "apiIngestMessage", "summary": "Send a message in", "description": "Take a message in from a custom channel. Free, always — including when the wallet is empty, so a ticket is never lost for want of credit.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `messages:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 1,200 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nRetry safely: the same `external_message_id` on the same channel is stored once.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry messages:write.\n- `not_found` — No such channel in this key’s environment.\n- `bad_request` — The payload is malformed — not JSON, no Content-Type: application/json, or a field of the wrong shape — or the body is over 32,000 characters.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.\n- `channel_disabled` — The channel is switched off in SlyOS. Nothing was stored.\n- `not_stored` — SlyOS could not store the message, and nothing was stored. Retry with the same external_message_id: it is stored once. If it keeps failing, keep the ticket on your side and tell us.", "tags": [ "Messages" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIngestMessageRequest" }, "example": { "channel_id": "3f6c2b1e-8a4d-4c7f-9e2b-5d1a7c9e0f42", "external_thread_id": "ticket-48213", "external_message_id": "ticket-48213-comment-2", "body": "Do you ship to Canada, and how long does delivery take?", "sender_identifier": "dana@example.com", "sender_display_name": "Dana Whitfield", "sent_at": "2026-10-09T15:42:07Z" } } } }, "responses": { "200": { "description": "This `external_message_id` was already stored on this channel; nothing new was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIngestMessageResponse" }, "example": { "message_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18", "thread_id": "c4a7e2d9-1b6f-4e83-9a50-7d2c8f1e3b65", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "duplicate": true, "needs_reply": true, "bulk": false } } } }, "201": { "description": "The message is new and was stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIngestMessageResponse" }, "example": { "message_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18", "thread_id": "c4a7e2d9-1b6f-4e83-9a50-7d2c8f1e3b65", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "duplicate": false, "needs_reply": true, "bulk": false } } } }, "400": { "description": "`bad_request` — The payload is malformed — not JSON, no Content-Type: application/json, or a field of the wrong shape — or the body is over 32,000 characters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The payload is malformed — not JSON, no Content-Type: application/json, or a field of the wrong shape — or the body is over 32,000 characters." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry messages:write.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry messages:write." } } } }, "404": { "description": "`not_found` — No such channel in this key’s environment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such channel in this key’s environment." } } } }, "409": { "description": "`channel_disabled` — The channel is switched off in SlyOS. Nothing was stored.\n\n`not_stored` — SlyOS could not store the message, and nothing was stored. Retry with the same external_message_id: it is stored once. If it keeps failing, keep the ticket on your side and tell us.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "channel_disabled", "not_stored" ] } } } ] }, "example": { "code": "channel_disabled", "message": "The channel is switched off in SlyOS. Nothing was stored." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "messages:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 1200, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/drafts": { "post": { "operationId": "apiGenerateDraft", "summary": "Ask for a reply", "description": "Ask SlyOS to write a reply, using the account’s Brain, voice and history. The one billable call: 10¢ per successful response, charged once per generation_id.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `drafts:generate` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 300 requests a minute; past it, `429 rate_limited`\n- **Cost:** 10¢ per AI response on a live key, charged once per `generation_id`; free in the sandbox\n\nThe reply is written by the account’s own Brain — what the business has taught SlyOS, the voice it has learned for the channel, and the conversation so far — through the same pipeline as the SlyOS inbox.\n\nThe only call that costs anything, and only on a live key. A request that does not produce a reply — refused, failed, or not needed — is not charged.\n\nCheck `held_for_review` before you send — on a replay too, which carries the hold the reply was written with. Send automatically only on `false`; `true` or `null` goes to a person, never straight to your customer, with `hold_reasons` saying why.\n\nA replay (`already_charged: true`) is a reply SlyOS already gave you once. If your first request may have sent it, do not send it again: check your own record of what went out.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry drafts:generate.\n- `bad_request` — The payload is malformed — a generation_id shorter than 8 or longer than 128 characters, an id that is not a UUID — or neither card_id nor message_id was given, or they name two different conversations.\n- `not_found` — No such message or card in this key’s environment. A sandbox key cannot reach a live card, and neither can reach another channel’s.\n- `no_card` — That message needs no reply, so there is nothing to draft.\n- `channel_paused` — The channel is paused on the Developer screen, so nothing is drafted on it. Nothing was charged.\n- `insufficient_funds` — No API credit remains. The message is still stored and visible, and can be answered by hand. Nothing was charged.\n- `generation_in_progress` — Another request with this generation_id is still being drafted. Retry after Retry-After with the same id to get that draft, charged once.\n- `generation_id_conflict` — That generation_id is already taken on this account. Nothing was charged.\n- `draft_gone` — The reply this generation_id produced was deleted with its conversation. Use a new generation_id.\n- `paused_identity` — Someone asked whether they are talking to a person; drafting is paused until the account owner clears it. Nothing was charged.\n- `paused_allowance` — Sandbox only: the plan’s AI allowance is used up, and sandbox drafts are drawn from the plan. Live drafts are paid from the wallet and never refused for this. Nothing was charged.\n- `filed_away` — The account owner archived or filed the conversation. Do not retry. Nothing was charged.\n- `no_reply_needed` — The model judged nobody is waiting for a reply (an automated message, say), so no draft was written. Nothing was charged.\n- `refused` — No draft could be produced for that card: its conversation or its channel could not be used. A card_id that does not exist is a 404 `not_found`, not this. Nothing was charged.\n- `ai_off` — The account owner has not allowed SlyOS to send their data to AI providers. Nothing was sent or charged. Do not retry until they allow it in the app.\n- `outage` — No model provider is reachable. Retry after Retry-After with the same generation_id. Nothing was charged.\n- `try_again` — The draft could not be charged for in time, so it was not. Retry with the same generation_id.\n- `drafting_unavailable` — Drafting is not configured on this deployment.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.\n- `sandbox_daily_limit` — Sandbox only: this account has had 50 sandbox drafts in the last 24 hours. Retry after Retry-After, or use a live key. A replay of a draft already written is not counted. Nothing was charged.", "tags": [ "Drafts" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiGenerateDraftRequest" }, "example": { "generation_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18:reply-1", "message_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18" } } } }, "responses": { "200": { "description": "A live key sent a `generation_id` that was already paid for: the same reply again, with the hold it was written with, charged nothing. It may already have been sent — do not send it again automatically.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiGenerateDraftResponse" }, "example": { "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "generation": 1, "body": "Hi Dana — yes, we ship to Canada. Orders usually arrive within 5–8 business days, and you’ll get a tracking link by email as soon as yours leaves our warehouse.", "held_for_review": false, "hold_reasons": [], "hold_detail": null, "billed_cents": 0, "already_charged": true, "originally_billed_cents": 10, "price_version": "2026-09-01", "environment": "live", "replayed": true, "generation_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18:reply-1", "sources": [ { "source_id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "passage_id": "2f9e4c1a-7b3d-4e8f-a5c2-6d1b9e3f7a40", "title": "Example Co — website", "url": "https://www.example.com/shipping", "page": null, "page_end": null, "section": "Shipping", "rule": false, "rank": 1, "score": 0.83, "excerpt": "We ship to the US and Canada. Orders leave our warehouse within two business days.", "text_sha256": "3b7e1f9a2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f", "carried_chars": null } ] } } } }, "201": { "description": "A reply was written for this `generation_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiGenerateDraftResponse" }, "example": { "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "generation": 1, "body": "Hi Dana — yes, we ship to Canada. Orders usually arrive within 5–8 business days, and you’ll get a tracking link by email as soon as yours leaves our warehouse.", "held_for_review": false, "hold_reasons": [], "hold_detail": null, "billed_cents": 10, "already_charged": false, "price_version": "2026-09-01", "environment": "live", "replayed": false, "generation_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18:reply-1", "sources": [ { "source_id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "passage_id": "2f9e4c1a-7b3d-4e8f-a5c2-6d1b9e3f7a40", "title": "Example Co — website", "url": "https://www.example.com/shipping", "page": null, "page_end": null, "section": "Shipping", "rule": false, "rank": 1, "score": 0.83, "excerpt": "We ship to the US and Canada. Orders leave our warehouse within two business days.", "text_sha256": "3b7e1f9a2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f", "carried_chars": null } ] } } } }, "400": { "description": "`bad_request` — The payload is malformed — a generation_id shorter than 8 or longer than 128 characters, an id that is not a UUID — or neither card_id nor message_id was given, or they name two different conversations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The payload is malformed — a generation_id shorter than 8 or longer than 128 characters, an id that is not a UUID — or neither card_id nor message_id was given, or they name two different conversations." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "402": { "description": "`insufficient_funds` — No API credit remains. The message is still stored and visible, and can be answered by hand. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiInsufficientFunds" }, "example": { "code": "insufficient_funds", "message": "This account has no API credit left. The message is stored and visible in SlyOS, and can still be answered by hand.", "available_cents": 9, "needed_cents": 10 } } } }, "403": { "description": "`missing_scope` — The key does not carry drafts:generate.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry drafts:generate." } } } }, "404": { "description": "`not_found` — No such message or card in this key’s environment. A sandbox key cannot reach a live card, and neither can reach another channel’s.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such message or card in this key’s environment. A sandbox key cannot reach a live card, and neither can reach another channel’s." } } } }, "409": { "description": "`no_card` — That message needs no reply, so there is nothing to draft.\n\n`channel_paused` — The channel is paused on the Developer screen, so nothing is drafted on it. Nothing was charged.\n\n`generation_in_progress` — Another request with this generation_id is still being drafted. Retry after Retry-After with the same id to get that draft, charged once.\n\n`generation_id_conflict` — That generation_id is already taken on this account. Nothing was charged.\n\n`draft_gone` — The reply this generation_id produced was deleted with its conversation. Use a new generation_id.\n\n`paused_identity` — Someone asked whether they are talking to a person; drafting is paused until the account owner clears it. Nothing was charged.\n\n`paused_allowance` — Sandbox only: the plan’s AI allowance is used up, and sandbox drafts are drawn from the plan. Live drafts are paid from the wallet and never refused for this. Nothing was charged.\n\n`filed_away` — The account owner archived or filed the conversation. Do not retry. Nothing was charged.\n\n`no_reply_needed` — The model judged nobody is waiting for a reply (an automated message, say), so no draft was written. Nothing was charged.\n\n`refused` — No draft could be produced for that card: its conversation or its channel could not be used. A card_id that does not exist is a 404 `not_found`, not this. Nothing was charged.\n\n`ai_off` — The account owner has not allowed SlyOS to send their data to AI providers. Nothing was sent or charged. Do not retry until they allow it in the app.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "no_card", "channel_paused", "generation_in_progress", "generation_id_conflict", "draft_gone", "paused_identity", "paused_allowance", "filed_away", "no_reply_needed", "refused", "ai_off" ] } } } ] }, "example": { "code": "no_card", "message": "That message needs no reply, so there is nothing to draft." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.\n\n`sandbox_daily_limit` — Sandbox only: this account has had 50 sandbox drafts in the last 24 hours. Retry after Retry-After, or use a live key. A replay of a draft already written is not counted. Nothing was charged.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiSandboxDailyLimit" }, { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } }, "503": { "description": "`outage` — No model provider is reachable. Retry after Retry-After with the same generation_id. Nothing was charged.\n\n`try_again` — The draft could not be charged for in time, so it was not. Retry with the same generation_id.\n\n`drafting_unavailable` — Drafting is not configured on this deployment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "outage", "try_again", "drafting_unavailable" ] } } } ] }, "example": { "code": "outage", "message": "No model provider is reachable. Retry after Retry-After with the same generation_id. Nothing was charged." } } } } }, "x-slyos-scope": "drafts:generate", "x-slyos-billable": true, "x-slyos-rate-limit-per-minute": 300, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/drafts/{draftId}": { "get": { "operationId": "apiReadDraft", "summary": "Read a reply back", "description": "Read a draft back. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `drafts:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 600 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry drafts:read.\n- `bad_request` — The draft id is not a UUID.\n- `not_found` — No such draft in this key’s environment.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Drafts" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "draftId", "in": "path", "required": true, "description": "The `draft_id` to read, from `POST /v1/developer/drafts` or `draft.ready`.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The draft exists on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReadDraftResponse" }, "example": { "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "body": "Hi Dana — yes, we ship to Canada. Orders usually arrive within 5–8 business days, and you’ll get a tracking link by email as soon as yours leaves our warehouse.", "generation": 1, "model": "claude-opus-5-5", "created_at": "2026-10-09T15:42:11.000Z", "held_for_review": false, "hold_reasons": [], "hold_detail": null, "superseded": false, "sources": [ { "source_id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "passage_id": "2f9e4c1a-7b3d-4e8f-a5c2-6d1b9e3f7a40", "title": "Example Co — website", "url": "https://www.example.com/shipping", "page": null, "page_end": null, "section": "Shipping", "rule": false, "rank": 1, "score": 0.83, "excerpt": "We ship to the US and Canada. Orders leave our warehouse within two business days.", "text_sha256": "3b7e1f9a2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f", "carried_chars": null } ] } } } }, "400": { "description": "`bad_request` — The draft id is not a UUID.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The draft id is not a UUID." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry drafts:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry drafts:read." } } } }, "404": { "description": "`not_found` — No such draft in this key’s environment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such draft in this key’s environment." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "drafts:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 600, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/deliveries": { "post": { "operationId": "apiAcknowledgeDelivery", "summary": "Report what happened to a send", "description": "Tell SlyOS what happened to the reply you sent through your own system. Recorded, and — given draft_id or body — written into the conversation so every SlyOS surface shows it. Free — we do not charge a customer for reporting their own send.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `deliveries:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 1,200 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nSend `draft_id` when you sent SlyOS’s draft as it was, or `body` with the text you actually sent. The reply then shows in the conversation on every SlyOS surface and its card closes; without either, the report is recorded and no text is invented for it.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry deliveries:write.\n- `bad_request` — The payload is malformed — message_id or draft_id is not a UUID, a body is empty or too long — or the status is not delivered, read or failed.\n- `not_found` — No such message in this key’s environment, or the draft named is not on that message’s conversation.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Deliveries" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAcknowledgeDeliveryRequest" }, "example": { "message_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18", "status": "delivered", "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "occurred_at": "2026-10-09T15:44:02Z" } } } }, "responses": { "200": { "description": "The report was recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAcknowledgeDeliveryResponse" }, "example": { "delivery_id": "4d7b1e9f-2a6c-4f35-b8e0-9c3a5f1d7e42", "message_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18", "status": "delivered", "recorded": true, "outbound_message_id": "b3e9c7a1-5d2f-4e86-a0c4-7f1b3d9e5a28", "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "card_closed": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14" } } } }, "400": { "description": "`bad_request` — The payload is malformed — message_id or draft_id is not a UUID, a body is empty or too long — or the status is not delivered, read or failed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The payload is malformed — message_id or draft_id is not a UUID, a body is empty or too long — or the status is not delivered, read or failed." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry deliveries:write.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry deliveries:write." } } } }, "404": { "description": "`not_found` — No such message in this key’s environment, or the draft named is not on that message’s conversation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such message in this key’s environment, or the draft named is not on that message’s conversation." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "deliveries:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 1200, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/usage": { "get": { "operationId": "apiUsage", "summary": "Read usage", "description": "Responses written for THIS key’s environment and project, and what they cost, over the last 30 days. Free. A sandbox key sees sandbox drafts at nought cents, never the account’s live spend.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `usage:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 120 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry usage:read.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Usage" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Always, for a valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUsageResponse" }, "example": { "environment": "live", "window_days": 30, "responses": 412, "charged_cents": 4120, "price": { "version": "2026-09-01", "cents_per_response": 10 } } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry usage:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry usage:read." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "usage:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 120, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/wallet": { "get": { "operationId": "apiWallet", "summary": "Check the balance", "description": "Balance, reserved, and how many responses remain — so an adapter can degrade before it is refused rather than after. A live key reads the wallet; a sandbox key reads no money at all (zeros) and how many of today’s free sandbox drafts are left.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `usage:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 240 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nCall it before a burst: an adapter that checks first can queue or hand over to a person before it is refused.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry usage:read.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Wallet" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Always, for a valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiWalletResponse" }, "example": { "environment": "live", "balance_cents": 1870, "reserved_cents": 10, "available_cents": 1860, "responses_remaining": 186 } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry usage:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry usage:read." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "usage:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 240, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/channels": { "post": { "operationId": "apiCreateChannel", "summary": "Create a channel", "description": "Create a custom channel. Its environment is the KEY’s — a live key makes a live channel — so a sandbox channel can never end up on live traffic by typo.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `channels:manage` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 60 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nThe environment is the key’s: a live key makes a live channel and a sandbox key a sandbox one. There is no field to say otherwise, so a sandbox channel cannot end up on live traffic by typo.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry channels:manage.\n- `bad_request` — The payload is malformed: no name, a name over 120 characters, or a capability outside the published set.\n- `no_slots` — Every channel slot on this plan is in use. Upgrade, or disconnect a channel first. Sandbox channels are free and do not count.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Channels" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCreateChannelRequest" }, "example": { "name": "Support desk", "system": "Zendesk", "capabilities": [ "receive", "send", "threading" ] } } } }, "responses": { "201": { "description": "The channel was created, in the key’s environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiChannel" }, "example": { "id": "3f6c2b1e-8a4d-4c7f-9e2b-5d1a7c9e0f42", "name": "Support desk", "system": "Zendesk", "environment": "sandbox", "capabilities": [ "receive", "send", "threading" ] } } } }, "400": { "description": "`bad_request` — The payload is malformed: no name, a name over 120 characters, or a capability outside the published set.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The payload is malformed: no name, a name over 120 characters, or a capability outside the published set." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "402": { "description": "`no_slots` — Every channel slot on this plan is in use. Upgrade, or disconnect a channel first. Sandbox channels are free and do not count.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "no_slots" ] } } } ] }, "example": { "code": "no_slots", "message": "Every channel slot on this plan is in use. Upgrade, or disconnect a channel first. Sandbox channels are free and do not count." } } } }, "403": { "description": "`missing_scope` — The key does not carry channels:manage.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry channels:manage." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "channels:manage", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 60, "x-slyos-rate-limit-enforced": true }, "get": { "operationId": "apiListChannels", "summary": "List channels", "description": "The custom channels this key can reach, with their declared capabilities. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `channels:manage` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 120 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry channels:manage.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "tags": [ "Channels" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Always, for a valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiListChannelsResponse" }, "example": { "channels": [ { "id": "3f6c2b1e-8a4d-4c7f-9e2b-5d1a7c9e0f42", "name": "Support desk", "system": "Zendesk", "environment": "sandbox", "capabilities": [ "receive", "send", "threading" ], "paused": false, "auto_draft": false, "last_inbound_at": "2026-10-09T15:42:08.000Z", "last_outbound_at": null } ], "known_capabilities": [ "receive", "send", "attachments", "read_receipts", "mark_read", "delivery_receipts", "reactions", "typing", "threading", "groups" ] } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry channels:manage.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry channels:manage." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key, sandbox included. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "channels:manage", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 120, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/sources": { "post": { "operationId": "apiAddKnowledge", "summary": "Add a link, a site or a file", "description": "Add a source: JSON {url, crawl?, rules?, title?, scope?} for a page or a whole site, or multipart with a `file` (PDF, Word, text, Markdown, CSV; up to 25 MB). Answers 202; the source is read in the background. Needs a live key.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:write` scope.\n- **Entitlement:** PDF pages a model reads, per account per 30 days: 100, or 2,000 on a paid plan or with money in the API wallet\n- **Rate limit:** 60 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nA link or a site is JSON: `{\"url\": \"…\"}`, with `\"crawl\": true` to read the whole site. A file is `multipart/form-data` with the file in a `file` field.\n\nMark terms, policies and regulations `rules`: replies must follow a rule, and draw on everything else as reference.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:write.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `sandbox_read_only` — A sandbox key can read knowledge but not change it.\n- `bad_request` — No url and no file, or an address SlyOS will not read.\n- `unsupported_type` — Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV).\n- `too_large` — The file is over 25 MB.\n- `too_many_sources` — The account already holds the most knowledge sources it may.\n- `knowledge_full` — The account already holds the most knowledge text it may.\n- `busy` — Too many sources are being read at once. Add more when they finish.\n- `uploads_busy` — Two files are already uploading for this account. Send the next after.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeLinkRequest" }, "example": { "url": "https://www.example.com/", "crawl": true } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeFileRequest" }, "example": { "file": "@returns-policy.pdf", "rules": "true", "title": "Returns policy" } } } }, "responses": { "200": { "description": "That address, or that exact file, is already a source: this is it, and nothing new was added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeResponse" }, "example": { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "kind": "site", "url": "https://www.example.com/", "filename": null, "title": "Example Co — website", "rules": false, "scope": "project", "status": "ready", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 24, "passages": 187, "characters": 96412, "size_bytes": null, "content_sha256": "4f2a9c0e7b1d3e5f6a8c9b0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f", "file_sha256": null, "used_in_replies": 38, "rules_fit": null, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:21:37.000Z", "fetched_at": "2026-10-09T15:21:37.000Z", "duplicate": true } } } }, "202": { "description": "Taken in. It is read in the background: poll `GET /v1/developer/knowledge/sources/{sourceId}` until `status` is `ready`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeResponse" }, "example": { "id": "0e7c2a9d-5f1b-4d38-a6e4-9b3c1f7d2a85", "kind": "file", "url": null, "filename": "returns-policy.pdf", "title": "Returns policy", "rules": true, "scope": "project", "status": "queued", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 0, "passages": 0, "characters": 0, "size_bytes": 284311, "content_sha256": null, "file_sha256": "9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c", "used_in_replies": 0, "rules_fit": true, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:20:04.000Z", "fetched_at": null, "duplicate": false } } } }, "400": { "description": "`bad_request` — No url and no file, or an address SlyOS will not read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "No url and no file, or an address SlyOS will not read." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:write.\n\n`sandbox_read_only` — A sandbox key can read knowledge but not change it.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope", "sandbox_read_only" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:write." } } } }, "409": { "description": "`too_many_sources` — The account already holds the most knowledge sources it may.\n\n`knowledge_full` — The account already holds the most knowledge text it may.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_many_sources", "knowledge_full" ] } } } ] }, "example": { "code": "too_many_sources", "message": "The account already holds the most knowledge sources it may." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "422": { "description": "`unsupported_type` — Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unsupported_type" ] } } } ] }, "example": { "code": "unsupported_type", "message": "Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV)." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n\n`busy` — Too many sources are being read at once. Add more when they finish.\n\n`uploads_busy` — Two files are already uploading for this account. Send the next after.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited", "busy", "uploads_busy" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 60, "x-slyos-rate-limit-enforced": true }, "get": { "operationId": "apiListKnowledge", "summary": "List knowledge sources", "description": "The sources this key’s replies use — its project’s and the account’s — with status. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 240 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:read.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Always, for a valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiListKnowledgeResponse" }, "example": { "sources": [ { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "kind": "site", "url": "https://www.example.com/", "filename": null, "title": "Example Co — website", "rules": false, "scope": "project", "status": "ready", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 24, "passages": 187, "characters": 96412, "size_bytes": null, "content_sha256": "4f2a9c0e7b1d3e5f6a8c9b0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f", "file_sha256": null, "used_in_replies": 38, "rules_fit": null, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:21:37.000Z", "fetched_at": "2026-10-09T15:21:37.000Z" } ] } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:read." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 240, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/sources/{sourceId}": { "get": { "operationId": "apiReadKnowledge", "summary": "Read a knowledge source", "description": "One source: status and why, pages and passages read, and how many replies relied on it. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 240 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:read.\n- `bad_request` — The source id is not a UUID.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `not_found` — No such source for this key.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "description": "A knowledge source’s `id`, from adding it or listing them.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The source exists for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeSource" }, "example": { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "kind": "site", "url": "https://www.example.com/", "filename": null, "title": "Example Co — website", "rules": false, "scope": "project", "status": "ready", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 24, "passages": 187, "characters": 96412, "size_bytes": null, "content_sha256": "4f2a9c0e7b1d3e5f6a8c9b0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f", "file_sha256": null, "used_in_replies": 38, "rules_fit": null, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:21:37.000Z", "fetched_at": "2026-10-09T15:21:37.000Z" } } } }, "400": { "description": "`bad_request` — The source id is not a UUID.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The source id is not a UUID." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:read." } } } }, "404": { "description": "`not_found` — No such source for this key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such source for this key." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 240, "x-slyos-rate-limit-enforced": true }, "patch": { "operationId": "apiUpdateKnowledge", "summary": "Mark a source as rules, or rename it", "description": "Mark a source as binding rules or as reference material, or rename it.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 60 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:write.\n- `bad_request` — The source id is not a UUID, or the body is malformed: nothing to change (send rules or title), or a title over 300 characters.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `sandbox_read_only` — A sandbox key can read knowledge but not change it.\n- `not_found` — No such source for this key.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "description": "A knowledge source’s `id`, from adding it or listing them.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUpdateKnowledgeRequest" }, "example": { "rules": true } } } }, "responses": { "200": { "description": "Changed. The next reply uses it as changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeSource" }, "example": { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "kind": "site", "url": "https://www.example.com/", "filename": null, "title": "Example Co — website", "rules": true, "scope": "project", "status": "ready", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 24, "passages": 187, "characters": 96412, "size_bytes": null, "content_sha256": "4f2a9c0e7b1d3e5f6a8c9b0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f", "file_sha256": null, "used_in_replies": 38, "rules_fit": true, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:21:37.000Z", "fetched_at": "2026-10-09T15:21:37.000Z" } } } }, "400": { "description": "`bad_request` — The source id is not a UUID, or the body is malformed: nothing to change (send rules or title), or a title over 300 characters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The source id is not a UUID, or the body is malformed: nothing to change (send rules or title), or a title over 300 characters." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:write.\n\n`sandbox_read_only` — A sandbox key can read knowledge but not change it.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope", "sandbox_read_only" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:write." } } } }, "404": { "description": "`not_found` — No such source for this key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such source for this key." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 60, "x-slyos-rate-limit-enforced": true }, "delete": { "operationId": "apiDeleteKnowledge", "summary": "Delete a source", "description": "Delete a source and every passage read from it. Replies stop using it at once.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 60 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:write.\n- `bad_request` — The source id is not a UUID.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `sandbox_read_only` — A sandbox key can read knowledge but not change it.\n- `not_found` — No such source for this key.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "description": "A knowledge source’s `id`, from adding it or listing them.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Deleted, with every passage read from it. No reply uses it from now on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDeleteKnowledgeResponse" }, "example": { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "deleted": true } } } }, "400": { "description": "`bad_request` — The source id is not a UUID.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The source id is not a UUID." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:write.\n\n`sandbox_read_only` — A sandbox key can read knowledge but not change it.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope", "sandbox_read_only" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:write." } } } }, "404": { "description": "`not_found` — No such source for this key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such source for this key." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 60, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/sources/{sourceId}/passages": { "get": { "operationId": "apiKnowledgePassages", "summary": "Read what was taken from a source", "description": "The passages read from a source, in order, with page, section and URL: exactly what replies retrieve from. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 120 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nExactly the passages replies retrieve from — check here what SlyOS read.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:read.\n- `bad_request` — The source id is not a UUID, or limit is not 1 to 200, or after is not a whole number from -1.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `not_found` — No such source for this key.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "description": "A knowledge source’s `id`, from adding it or listing them.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "description": "How many passages to return.", "schema": { "default": 50, "description": "How many passages to return.", "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "after", "in": "query", "required": false, "description": "Return passages after this `ordinal`: the previous page’s `next_after`.", "schema": { "default": -1, "description": "Return passages after this `ordinal`: the previous page’s `next_after`.", "type": "integer", "minimum": -1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The source exists for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgePassagesResponse" }, "example": { "source_id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "passages": [ { "id": "2f9e4c1a-7b3d-4e8f-a5c2-6d1b9e3f7a40", "ordinal": 0, "page": null, "page_end": null, "section": "Shipping", "url": "https://www.example.com/shipping", "text": "We ship to the US and Canada. Orders leave our warehouse within two business days." } ], "next_after": null } } } }, "400": { "description": "`bad_request` — The source id is not a UUID, or limit is not 1 to 200, or after is not a whole number from -1.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The source id is not a UUID, or limit is not 1 to 200, or after is not a whole number from -1." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:read." } } } }, "404": { "description": "`not_found` — No such source for this key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such source for this key." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 120, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/sources/{sourceId}/refresh": { "post": { "operationId": "apiRefreshKnowledge", "summary": "Read a link or a site again", "description": "Read a link or a site again. The copy already read keeps answering until the new one is ready.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 30 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nRefresh after your site or a regulation page changes; replies use the new text once it is `ready`.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:write.\n- `bad_request` — The source id is not a UUID.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `sandbox_read_only` — A sandbox key can read knowledge but not change it.\n- `not_found` — No such source for this key.\n- `cannot_refresh` — A file is read once and not kept. Upload the new version instead.\n- `busy` — That source is being read right now.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sourceId", "in": "path", "required": true, "description": "A knowledge source’s `id`, from adding it or listing them.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "202": { "description": "Queued. The copy already read keeps answering until the new one is ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeSource" }, "example": { "id": "6b1d4f8a-3c2e-4a9f-b7d0-1e5c8a2f4d63", "kind": "site", "url": "https://www.example.com/", "filename": null, "title": "Example Co — website", "rules": false, "scope": "project", "status": "queued", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 24, "passages": 187, "characters": 96412, "size_bytes": null, "content_sha256": "4f2a9c0e7b1d3e5f6a8c9b0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f", "file_sha256": null, "used_in_replies": 38, "rules_fit": null, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:21:37.000Z", "fetched_at": "2026-10-09T15:21:37.000Z" } } } }, "400": { "description": "`bad_request` — The source id is not a UUID.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The source id is not a UUID." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:write.\n\n`sandbox_read_only` — A sandbox key can read knowledge but not change it.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope", "sandbox_read_only" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:write." } } } }, "404": { "description": "`not_found` — No such source for this key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "No such source for this key." } } } }, "409": { "description": "`cannot_refresh` — A file is read once and not kept. Upload the new version instead.\n\n`busy` — That source is being read right now.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "cannot_refresh", "busy" ] } } } ] }, "example": { "code": "cannot_refresh", "message": "A file is read once and not kept. Upload the new version instead." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 30, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/profile": { "get": { "operationId": "apiBusinessProfile", "summary": "Read the business profile", "description": "The business profile this key’s replies use: name, description, tone notes. Free.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:read` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 120 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:read.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Always, for a valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBusinessProfile" }, "example": { "business_name": "Example Co", "description": "We make and sell refillable kitchen goods online, shipping to the US and Canada. We do not take phone orders.", "tone_notes": "Warm and brief. Sign off as “The Example Co team”.", "use_personal_context": true, "updated_at": "2026-10-09T15:18:52.000Z" } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:read.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:read." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:read", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 120, "x-slyos-rate-limit-enforced": true }, "put": { "operationId": "apiSaveBusinessProfile", "summary": "Say who the business is and how it sounds", "description": "Set what the business is and how it wants to sound. Used in every API reply of this key’s project.\n\n- **Auth:** an API key (`sly_test_…` or `sly_live_…`) carrying the `brain:write` scope.\n- **Entitlement:** none — every tier may call it\n- **Rate limit:** 30 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nA field you leave out is left as it was; `null` clears it. Whether replies use everything SlyOS knows about the owner (`use_personal_context`) is the owner’s switch, on the Developer screen: a key may send back the value `GET` answered, and a key that tries to change it is refused.\n\n**Errors**\n- `unauthorized` — The key is missing, malformed, revoked, or not one we issued.\n- `missing_scope` — The key does not carry brain:write.\n- `rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.\n- `sandbox_read_only` — A sandbox key can read knowledge but not change it.\n- `bad_request` — The body is malformed — a field this route does not take, or one longer than it may be — or it tries to change use_personal_context, which only the account owner can, on the Developer screen.", "tags": [ "Knowledge" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSaveBusinessProfileRequest" }, "example": { "business_name": "Example Co", "description": "We make and sell refillable kitchen goods online, shipping to the US and Canada. We do not take phone orders.", "tone_notes": "Warm and brief. Sign off as “The Example Co team”." } } } }, "responses": { "200": { "description": "Saved. Every reply asked for with this key’s project uses it from now on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBusinessProfile" }, "example": { "business_name": "Example Co", "description": "We make and sell refillable kitchen goods online, shipping to the US and Canada. We do not take phone orders.", "tone_notes": "Warm and brief. Sign off as “The Example Co team”.", "use_personal_context": true, "updated_at": "2026-10-09T15:18:52.000Z" } } } }, "400": { "description": "`bad_request` — The body is malformed — a field this route does not take, or one longer than it may be — or it tries to change use_personal_context, which only the account owner can, on the Developer screen.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "The body is malformed — a field this route does not take, or one longer than it may be — or it tries to change use_personal_context, which only the account owner can, on the Developer screen." } } } }, "401": { "description": "`unauthorized` — The key is missing, malformed, revoked, or not one we issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unauthorized" ] } } } ] }, "example": { "code": "unauthorized", "message": "The key is missing, malformed, revoked, or not one we issued." } } } }, "403": { "description": "`missing_scope` — The key does not carry brain:write.\n\n`sandbox_read_only` — A sandbox key can read knowledge but not change it.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "missing_scope", "sandbox_read_only" ] } } } ] }, "example": { "code": "missing_scope", "message": "The key does not carry brain:write." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account and per key. Wait a minute.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account and per key. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-scope": "brain:write", "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 30, "x-slyos-rate-limit-enforced": true } }, "/v1/developer/knowledge/uploads/{token}": { "post": { "operationId": "apiKnowledgeUpload", "summary": "Upload a file to a one-time address", "description": "Where the account’s own screen uploads a file directly (multipart `file`), with a one-time token from developerKnowledgeUploadUrl in place of a key.\n\n- **Auth:** no API key — this step is authorised by what its URL carries.\n- **Entitlement:** PDF pages a model reads, per account per 30 days: 100, or 2,000 on a paid plan or with money in the API wallet\n- **Rate limit:** 30 requests a minute; past it, `429 rate_limited`\n- **Cost:** free\n\nFor the Developer screen’s own uploads: the address carries a one-time token in place of a key. From your server, use `POST /v1/developer/knowledge/sources`.\n\n**Errors**\n- `not_found` — The upload address is unknown, used, or expired. Ask for a new one.\n- `rate_limited` — Over this route’s per-minute limit, counted per account. Wait a minute.\n- `too_many_sources` — The account already holds the most knowledge sources it may.\n- `knowledge_full` — The account already holds the most knowledge text it may.\n- `busy` — Too many sources are being read at once. Add more when they finish.\n- `uploads_busy` — Two files are already uploading for this account. Send the next after.\n- `bad_request` — No file in the upload, or the upload address is malformed.\n- `unsupported_type` — Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV).\n- `too_large` — The file is over 25 MB.", "tags": [ "Knowledge" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The one-time token in the upload address SlyOS gave the Developer screen.", "schema": { "type": "string", "minLength": 20, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeUploadRequest" }, "example": { "file": "@returns-policy.pdf", "title": "Returns policy" } } } }, "responses": { "200": { "description": "That exact file is already a source: this is it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeResponse" }, "example": { "id": "0e7c2a9d-5f1b-4d38-a6e4-9b3c1f7d2a85", "kind": "file", "url": null, "filename": "returns-policy.pdf", "title": "Returns policy", "rules": true, "scope": "project", "status": "ready", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 0, "passages": 0, "characters": 0, "size_bytes": 284311, "content_sha256": null, "file_sha256": "9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c", "used_in_replies": 0, "rules_fit": true, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:20:04.000Z", "fetched_at": null, "duplicate": true } } } }, "202": { "description": "Taken in, and read in the background.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAddKnowledgeResponse" }, "example": { "id": "0e7c2a9d-5f1b-4d38-a6e4-9b3c1f7d2a85", "kind": "file", "url": null, "filename": "returns-policy.pdf", "title": "Returns policy", "rules": true, "scope": "project", "status": "queued", "status_reason": null, "warning": null, "incomplete_pages": [], "pages": 0, "passages": 0, "characters": 0, "size_bytes": 284311, "content_sha256": null, "file_sha256": "9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c", "used_in_replies": 0, "rules_fit": true, "rules_note": null, "created_at": "2026-10-09T15:20:04.000Z", "updated_at": "2026-10-09T15:20:04.000Z", "fetched_at": null, "duplicate": false } } } }, "400": { "description": "`bad_request` — No file in the upload, or the upload address is malformed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "bad_request" ] } } } ] }, "example": { "code": "bad_request", "message": "No file in the upload, or the upload address is malformed." } } } }, "404": { "description": "`not_found` — The upload address is unknown, used, or expired. Ask for a new one.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "not_found" ] } } } ] }, "example": { "code": "not_found", "message": "The upload address is unknown, used, or expired. Ask for a new one." } } } }, "409": { "description": "`too_many_sources` — The account already holds the most knowledge sources it may.\n\n`knowledge_full` — The account already holds the most knowledge text it may.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_many_sources", "knowledge_full" ] } } } ] }, "example": { "code": "too_many_sources", "message": "The account already holds the most knowledge sources it may." } } } }, "413": { "description": "`too_large` — The request body is larger than this endpoint accepts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "too_large" ] } } } ] }, "example": { "code": "too_large", "message": "The request body is larger than this endpoint accepts." } } } }, "422": { "description": "`unsupported_type` — Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "unsupported_type" ] } } } ] }, "example": { "code": "unsupported_type", "message": "Not a file type SlyOS reads (PDF, Word .docx, plain text, Markdown, CSV)." } } } }, "429": { "description": "`rate_limited` — Over this route’s per-minute limit, counted per account. Wait a minute.\n\n`busy` — Too many sources are being read at once. Add more when they finish.\n\n`uploads_busy` — Two files are already uploading for this account. Send the next after.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "rate_limited", "busy", "uploads_busy" ] } } } ] }, "example": { "code": "rate_limited", "message": "Over this route’s per-minute limit, counted per account. Wait a minute." } } } }, "500": { "description": "`internal` — An unexpected fault on SlyOS’s side. It is recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiRefusal" }, { "properties": { "code": { "enum": [ "internal" ] } } } ] }, "example": { "code": "internal", "message": "An unexpected fault on SlyOS’s side. It is recorded." } } } } }, "x-slyos-billable": false, "x-slyos-rate-limit-per-minute": 30, "x-slyos-rate-limit-enforced": true } } }, "webhooks": { "draft.ready": { "post": { "operationId": "webhook_draft_ready", "summary": "A reply is ready", "description": "Sent after `POST /v1/developer/drafts` writes a reply, to the endpoint set for the environment of the key that asked — a sandbox reply to the sandbox endpoint, a live one to the live endpoint. Retried until it is answered `2xx`, under the same `id`: deduplicate on it. It carries the hold: send automatically only when `held_for_review` is `false`; `true` or `null` goes to a person. Read the reply’s text with `GET /v1/developer/drafts/{draftId}`, which carries the same hold. The same reply also came back in the `POST` answer: if your integration sends from that answer, do not send it again from this event.\n\nSigned with `SlyOS-Signature`; verify it before reading a single field of the body.", "tags": [ "Webhooks" ], "parameters": [ { "name": "SlyOS-Signature", "in": "header", "required": true, "description": "`t=,v1=`. The `v1` value is HMAC-SHA256, keyed with your endpoint's signing secret, of the string `\".\"`.\n\nTo verify: split on commas; read `t`; refuse the delivery if `t` is more than 300 seconds from your clock; compute the HMAC over the RAW body bytes you received (not re-serialised JSON); accept if it equals ANY `v1=` value, compared in constant time.\n\nDuring a secret rotation the header carries two `v1=` values, one per secret, until the old one expires — which is why the rule is \"any\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftReadyEvent" }, "example": { "id": "8c2f6e1a-4b7d-4a93-9e05-3f1c7a2d6b58", "type": "draft.ready", "created": 1791560531, "environment": "live", "data": { "draft_id": "e1f7a3c5-9d2b-4e68-b0a4-6c3e8f1d2a97", "card_id": "5e8d1c3a-7f24-4b9e-8c61-0a3f9d2e7b14", "generation_id": "9b2e4f71-3c8a-4d5e-a1f6-2e7b9c0d4a18:reply-1", "generation": 1, "environment": "live", "held_for_review": false, "hold_reasons": [], "hold_detail": null } } } } }, "responses": { "2XX": { "description": "Received. Answer quickly and do the work afterwards. Any other answer, or none, is recorded as a failed attempt on the Developer screen." } } } }, "webhook.test": { "post": { "operationId": "webhook_webhook_test", "summary": "A test delivery", "description": "Sent when the account owner presses Send test on the Developer screen, to that environment’s endpoint. Sent once and never retried. Nothing happened; use it to check your signature verification.\n\nSigned with `SlyOS-Signature`; verify it before reading a single field of the body.", "tags": [ "Webhooks" ], "parameters": [ { "name": "SlyOS-Signature", "in": "header", "required": true, "description": "`t=,v1=`. The `v1` value is HMAC-SHA256, keyed with your endpoint's signing secret, of the string `\".\"`.\n\nTo verify: split on commas; read `t`; refuse the delivery if `t` is more than 300 seconds from your clock; compute the HMAC over the RAW body bytes you received (not re-serialised JSON); accept if it equals ANY `v1=` value, compared in constant time.\n\nDuring a secret rotation the header carries two `v1=` values, one per secret, until the old one expires — which is why the rule is \"any\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestEvent" }, "example": { "id": "1a9d3f7c-6e2b-4c48-8b1f-5d0e9a3c7f26", "type": "webhook.test", "created": 1791560400, "environment": "sandbox", "data": { "message": "This is a test delivery from SlyOS. Nothing happened." } } } } }, "responses": { "2XX": { "description": "Received. Answer quickly and do the work afterwards. Any other answer, or none, is recorded as a failed attempt on the Developer screen." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sly_test_… or sly_live_…", "description": "A Developer API key, sent as `Authorization: Bearer `. Keys starting `sly_test_` are the sandbox — free, and they reach nobody. Keys starting `sly_live_` are live. Create keys in SlyOS under Settings → Plan → Developer; each is shown once." } }, "schemas": { "ApiAcknowledgeDeliveryRequest": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The SlyOS `message_id` the reply answered — the id ingest returned." }, "status": { "type": "string", "enum": [ "delivered", "read", "failed" ], "description": "What happened, as your system saw it." }, "detail": { "description": "Your system’s own note — a provider’s error text, for example.", "type": "string", "maxLength": 512 }, "occurred_at": { "description": "When it happened: ISO 8601 in UTC, ending in `Z`.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "draft_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The SlyOS draft you sent, as it was. The reply then appears in the conversation, and the card it answered closes as sent." }, "body": { "description": "The text you actually sent, when a person edited the draft or wrote it. Wins over `draft_id`'s text when both are given. At most 32,000 characters.", "type": "string", "minLength": 1, "maxLength": 32000 }, "external_message_id": { "description": "Your own id for the message you sent. Reporting the same one again is still one message in the conversation.", "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "message_id", "status" ] }, "ApiAcknowledgeDeliveryResponse": { "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "SlyOS’s record of this report." }, "message_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message the report was about." }, "status": { "type": "string", "enum": [ "delivered", "read", "failed" ], "description": "The status you reported." }, "recorded": { "type": "boolean", "const": true, "description": "Always true on a 200: the report was stored." }, "outbound_message_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The reply as it now appears in the conversation." }, { "type": "null" } ], "description": "The reply as it now appears in the conversation. Null when no text was given (`draft_id` or `body`), or the status was not `delivered`." }, "draft_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The SlyOS draft this was." }, { "type": "null" } ], "description": "The SlyOS draft this was — named by `draft_id`, or matched by its words. Null when the words were not SlyOS’s." }, "card_closed": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The card this reply closed." }, { "type": "null" } ], "description": "The card this reply closed as sent. Null when it closed none." } }, "required": [ "delivery_id", "message_id", "status", "recorded", "outbound_message_id", "draft_id", "card_closed" ] }, "ApiAddKnowledgeFileRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file — PDF, Word (.docx), plain text, Markdown or CSV, up to the size this operation states. It is read to the end; a long one is cut into passages, not cut short." }, "rules": { "description": "`true` when replies must follow this file rather than draw on it. Default `false`.", "type": "string", "enum": [ "true", "false" ] }, "title": { "description": "What to call it on the Developer screen and in a reply’s `sources`.", "type": "string" }, "scope": { "type": "string", "enum": [ "project", "account" ], "description": "`project`: replies asked for with this key’s project use it. `account`: replies in every project on the account do." } }, "required": [ "file" ] }, "ApiAddKnowledgeLinkRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "A public http(s) address: one page — your pricing page, a policy, a regulation — or, with `crawl`, the start of a whole site." }, "crawl": { "description": "Read the whole site from this address: the same site only, robots.txt respected, up to the page limit this operation states. Default: this page alone.", "type": "boolean" }, "rules": { "description": "True when replies must FOLLOW this source — terms, a policy, a regulation — rather than draw on it as reference. Default false.", "type": "boolean" }, "title": { "description": "What to call it on the Developer screen and in a reply’s `sources`.", "type": "string", "maxLength": 300 }, "scope": { "type": "string", "enum": [ "project", "account" ], "description": "`project`: replies asked for with this key’s project use it. `account`: replies in every project on the account do." } }, "required": [ "url" ] }, "ApiAddKnowledgeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The source’s id." }, "kind": { "type": "string", "enum": [ "link", "site", "file" ], "description": "`link`: one page. `site`: a whole site, read from one address. `file`: an upload." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address it is read from. Null for a file." }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The uploaded file’s name. Null for a link or a site." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What it is called on the Developer screen and in a reply’s `sources`." }, "rules": { "type": "boolean", "description": "True when replies must follow it; false when it is reference material." }, "scope": { "type": "string", "enum": [ "project", "account" ], "description": "`project`: replies asked for with this key’s project use it. `account`: replies in every project on the account do." }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ], "description": "`queued`, then `processing`, while it is read in the background; `ready` once replies use it; `failed` when it could not be read, with `status_reason` saying why." }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "In a sentence, why the status is what it is. Null when there is nothing to say." }, "warning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the source is `ready` but some of what it shows may be missing, in a sentence naming the pages and what to do — today, pages that build their content with JavaScript, which SlyOS does not run (a price list drawn from a script, a template filled in after the page loads). Null when there is nothing to warn about." }, "incomplete_pages": { "type": "array", "items": { "type": "string" }, "description": "The addresses of the pages `warning` names: pages whose content is built with JavaScript, so replies may be missing what a visitor sees there. Add that text as a file, or as a single link to a page that shows it. Empty when there are none." }, "pages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Pages read from it." }, "passages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Passages it was cut into: what a reply retrieves from." }, "characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Characters of text read from it." }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The uploaded file’s size. Null for a link or a site." }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the text read from it; it changes when a refresh reads something new." }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the uploaded file’s bytes. Null for a link or a site." }, "used_in_replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many replies have relied on a passage of it." }, "rules_fit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "For a rules source: true when every one of the business’s rules reaches every reply; false when they no longer fit in one reply, and each reply gets the rules nearest its message. Null for reference material, or when it was not measured." }, "rules_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When `rules_fit` is false, in a sentence: how much the rules come to, what one reply carries, and what to do about it." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was added." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it last changed." }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was last read. Null until it has been." }, { "type": "null" } ] }, "duplicate": { "type": "boolean", "description": "True when this address or this exact file was already a source: nothing new was added, and this is that source." } }, "required": [ "id", "kind", "url", "filename", "title", "rules", "scope", "status", "status_reason", "warning", "incomplete_pages", "pages", "passages", "characters", "size_bytes", "content_sha256", "file_sha256", "used_in_replies", "rules_fit", "rules_note", "created_at", "updated_at", "fetched_at", "duplicate" ] }, "ApiBusinessProfile": { "type": "object", "properties": { "business_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The business’s name, as replies give it." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the business is and does, in its own words." }, "tone_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How replies should sound." }, "use_personal_context": { "type": "boolean", "description": "Whether API replies also use everything SlyOS knows about the account owner: facts from their own conversations and the ones they told it, their past replies on their other channels, their documents, calendar and saved details, and their About you. On unless the owner turned it off on the Developer screen; a key cannot change it. Off, a reply still uses the owner’s name, rules and writing style. Either way, nothing one customer wrote or was sent goes into another customer’s reply, and nothing from a sandbox conversation goes into a live one; every reply the account sends still shapes its writing style." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When the profile last changed. Null if it never has." }, { "type": "null" } ] } }, "required": [ "business_name", "description", "tone_notes", "use_personal_context", "updated_at" ] }, "ApiChannel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The channel’s id: the `channel_id` every message sent to it names." }, "name": { "type": "string", "description": "Its name on every SlyOS screen." }, "system": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The system behind it, if you named one." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The environment of the key that made the call: `sandbox` or `live`." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "receive", "send", "attachments", "read_receipts", "mark_read", "delivery_receipts", "reactions", "typing", "threading", "groups" ] }, "description": "What the adapter declared it can do." } }, "required": [ "id", "name", "system", "environment", "capabilities" ] }, "ApiCreateChannelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What the channel is called on every SlyOS screen." }, "system": { "description": "The system behind it, for your own reference — “Zendesk”, “our app chat”.", "type": "string", "maxLength": 120 }, "capabilities": { "description": "What your adapter can actually do on this channel. SlyOS never assumes one it was not told. Defaults to `[\"receive\", \"send\"]`.", "type": "array", "items": { "type": "string", "enum": [ "receive", "send", "attachments", "read_receipts", "mark_read", "delivery_receipts", "reactions", "typing", "threading", "groups" ] } } }, "required": [ "name" ] }, "ApiDeleteKnowledgeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The source that was deleted." }, "deleted": { "type": "boolean", "const": true, "description": "Always true on a 200." } }, "required": [ "id", "deleted" ] }, "ApiGenerateDraftRequest": { "type": "object", "properties": { "generation_id": { "type": "string", "minLength": 8, "maxLength": 128, "description": "Your id for this one reply, and the idempotency key for the charge: sending the same `generation_id` again does not buy a second reply. It is yours alone — unique within your account and the key’s environment, never shared with another account. Make it unique and reproducible — derive it from the `message_id` SlyOS gave you, e.g. `:reply-1`, and use `:reply-2` for a deliberate second reply. An id already used for a different conversation is refused (409 `generation_id_conflict`), never answered with that conversation’s reply." }, "card_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The card to reply on. Give this or `message_id`." }, "message_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "A `message_id` from `POST /v1/developer/messages`. SlyOS replies on the card that message opened. Give this or `card_id`." }, "instruction": { "description": "A one-off steer for this reply, in plain words — for example “Offer a call on Thursday.” At most 2,000 characters.", "type": "string", "maxLength": 2000 } }, "required": [ "generation_id" ] }, "ApiGenerateDraftResponse": { "type": "object", "properties": { "draft_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The draft’s id. `GET /v1/developer/drafts/{draftId}` reads it back." }, "card_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The card the reply is for." }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Which draft this is on the card: 1 for the first, higher after another reply was asked for." }, "body": { "type": "string", "description": "The reply text." }, "held_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when SlyOS’s checks held this reply for a person — money, health or dosing, a legal or data-protection matter, another sensitive subject, or something it gives out that the account has not sent before. Never send a held reply automatically: show it to a person first. Null when SlyOS can no longer say, because the conversation has had a newer reply since; null means held. Send automatically only on `false`." }, "hold_reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Which check held it: `sensitive` (money, legal, health or credentials), `attachment` (it carries a file), `group` (it goes to a group), `regex_floor` (it matches a rule you set), `outbound_screen` (it gives out something not sent before, or answers a risky request). A code not listed here is still a hold — treat every code you do not recognise as one." }, "label": { "type": "string", "description": "The same reason in words, as the SlyOS inbox shows it." } }, "required": [ "code", "label" ] }, "description": "Why it was held: one entry per check that held it. Empty when `held_for_review` is not `true`." }, "hold_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the checks found, in sentences, when the reply was held. Null when it was not held, or when SlyOS cannot say." }, "billed_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "What THIS request was charged: the price on a live key’s first success, 0 on a replay and in the sandbox." }, "already_charged": { "type": "boolean", "description": "True when this `generation_id` had already been paid for and this response is that same reply again." }, "originally_billed_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Only on a replay: what the original generation was charged." }, "price_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The price version the charge was made under. Null in the sandbox." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The environment of the key that made the call: `sandbox` or `live`." }, "replayed": { "type": "boolean", "description": "True when this answer is a reply SlyOS already wrote for this `generation_id` — in the sandbox too, where nothing is charged. It may already have been sent: do not send it again automatically." }, "generation_id": { "type": "string", "description": "The `generation_id` you sent, echoed." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The knowledge source the passage came from. Null once that source is deleted." }, { "type": "null" } ] }, "passage_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The passage itself. Null once its source is deleted." }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the source was called when the reply was written: its title, file name or address." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The page the passage was read from, for a link or a site." }, "page": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The page of the file its own text starts on, for a file that has pages. With `page_end`, the range it covers." }, "page_end": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The last page it runs onto, when it runs past `page` — a passage starting on page 11 and carrying page 12 is `page: 11, page_end: 12` (p.11–12). Null when it stays on one page, or the file has no pages." }, "section": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The heading it sat under, if any." }, "rule": { "type": "boolean", "description": "True for a binding rule the reply had to follow; false for reference material it could draw on." }, "rank": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Its place in what the reply was given, from 1 — counted separately for rules and for reference." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How close the passage was to the message, as cosine similarity. Null when there was nothing to compare." }, "excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Up to 280 characters of the passage’s OWN text — past the lines it repeats from the passage before it — from the sentence that shares the most words with the reply, else from its start; `…` marks a cut. While its source still exists." }, "text_sha256": { "type": "string", "description": "SHA-256 of the stored passage the reply was given — all of it, or its first `carried_chars` characters: proof of which text it relied on, even after the source changes." }, "carried_chars": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How many of the passage’s characters the reply was given, when it was cut to fit. Null when it was given the whole passage." } }, "required": [ "source_id", "passage_id", "title", "url", "page", "page_end", "section", "rule", "rank", "score", "excerpt", "text_sha256", "carried_chars" ] }, "description": "What this reply relied on: every passage of the business’s own knowledge — the links, sites and files it handed SlyOS, and its rules — that the reply was given, rules first. Empty when the reply was given none: the business has handed SlyOS nothing yet, or nothing it handed over matched." } }, "required": [ "draft_id", "card_id", "generation", "body", "held_for_review", "hold_reasons", "hold_detail", "billed_cents", "already_charged", "price_version", "environment", "replayed", "generation_id", "sources" ] }, "ApiIngestMessageRequest": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The custom channel the message arrived on: an `id` from `GET /v1/developer/channels`. It must belong to the same environment as the key." }, "external_thread_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Your id for the conversation — a ticket, a chat. Messages that share one are one conversation in SlyOS." }, "external_message_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Your id for this message. Sending the same one on the same channel again stores nothing new and answers 200 with `duplicate: true`, so a retry is always safe." }, "body": { "type": "string", "minLength": 1, "maxLength": 32000, "description": "The message text, as the sender wrote it. At most 32,000 characters." }, "sent_at": { "description": "When it was sent: ISO 8601 in UTC, ending in `Z`. An offset such as `+01:00` is refused. Defaults to when SlyOS received it.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "sender_identifier": { "description": "Who sent it, as your system knows them — an email address, a phone number or a handle. SlyOS uses it to recognise the same person across messages. Leave it out rather than send it blank.", "type": "string", "maxLength": 512, "pattern": "\\S" }, "sender_display_name": { "description": "The sender’s name, as it should be shown.", "type": "string", "maxLength": 256 }, "subject": { "description": "A subject line, for channels that have one.", "type": "string", "maxLength": 512 }, "thread_title": { "description": "A title for the conversation, shown in the SlyOS inbox.", "type": "string", "maxLength": 512 }, "direction": { "default": "inbound", "description": "`inbound` (the default) for a message your customer sent. `outbound` for a reply your side sent, so SlyOS’s copy of the conversation is complete.", "type": "string", "enum": [ "inbound", "outbound" ] } }, "required": [ "channel_id", "external_thread_id", "external_message_id", "body" ] }, "ApiIngestMessageResponse": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "SlyOS’s id for the message. Ask for a draft with it." }, "thread_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "SlyOS’s id for the conversation." }, "card_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The reply card this message opened." }, { "type": "null" } ], "description": "The reply card this message opened, or null when it needs no reply." }, "duplicate": { "type": "boolean", "description": "True when this `external_message_id` was already stored on this channel. Nothing new was written." }, "needs_reply": { "type": "boolean", "description": "False when SlyOS decided nobody is waiting for an answer — a receipt, a newsletter. Do not ask for a draft then." }, "bulk": { "type": "boolean", "description": "True when the message was recognised as bulk mail. It is stored and shown, with no card." } }, "required": [ "message_id", "thread_id", "card_id", "duplicate", "needs_reply", "bulk" ] }, "ApiInsufficientFunds": { "type": "object", "properties": { "code": { "type": "string", "const": "insufficient_funds", "description": "Always `insufficient_funds`." }, "message": { "type": "string", "description": "One sentence, written for a person." }, "available_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "What the wallet could spend when the request arrived." }, "needed_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "What the reply would have cost." } }, "required": [ "code", "message", "available_cents", "needed_cents" ] }, "ApiKnowledgePassagesResponse": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The source the passages belong to." }, "passages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The passage’s id: a reply’s `sources[].passage_id`." }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Its place in the source, from 0." }, "page": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The page of the file its own text starts on, if the file has pages." }, "page_end": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The last page it runs onto, when it runs past `page`. Null when it stays on one page, the file has no pages, or it was read before page ranges were recorded." }, "section": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The heading it sits under, if any." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The page of a site it was read from." }, "text": { "type": "string", "description": "The passage, exactly as replies are given it." } }, "required": [ "id", "ordinal", "page", "page_end", "section", "url", "text" ] }, "description": "The passages, in order." }, "next_after": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pass as `after` for the next page. Null on the last page." } }, "required": [ "source_id", "passages", "next_after" ] }, "ApiKnowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The source’s id." }, "kind": { "type": "string", "enum": [ "link", "site", "file" ], "description": "`link`: one page. `site`: a whole site, read from one address. `file`: an upload." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address it is read from. Null for a file." }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The uploaded file’s name. Null for a link or a site." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What it is called on the Developer screen and in a reply’s `sources`." }, "rules": { "type": "boolean", "description": "True when replies must follow it; false when it is reference material." }, "scope": { "type": "string", "enum": [ "project", "account" ], "description": "`project`: replies asked for with this key’s project use it. `account`: replies in every project on the account do." }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ], "description": "`queued`, then `processing`, while it is read in the background; `ready` once replies use it; `failed` when it could not be read, with `status_reason` saying why." }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "In a sentence, why the status is what it is. Null when there is nothing to say." }, "warning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the source is `ready` but some of what it shows may be missing, in a sentence naming the pages and what to do — today, pages that build their content with JavaScript, which SlyOS does not run (a price list drawn from a script, a template filled in after the page loads). Null when there is nothing to warn about." }, "incomplete_pages": { "type": "array", "items": { "type": "string" }, "description": "The addresses of the pages `warning` names: pages whose content is built with JavaScript, so replies may be missing what a visitor sees there. Add that text as a file, or as a single link to a page that shows it. Empty when there are none." }, "pages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Pages read from it." }, "passages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Passages it was cut into: what a reply retrieves from." }, "characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Characters of text read from it." }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The uploaded file’s size. Null for a link or a site." }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the text read from it; it changes when a refresh reads something new." }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the uploaded file’s bytes. Null for a link or a site." }, "used_in_replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many replies have relied on a passage of it." }, "rules_fit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "For a rules source: true when every one of the business’s rules reaches every reply; false when they no longer fit in one reply, and each reply gets the rules nearest its message. Null for reference material, or when it was not measured." }, "rules_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When `rules_fit` is false, in a sentence: how much the rules come to, what one reply carries, and what to do about it." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was added." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it last changed." }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was last read. Null until it has been." }, { "type": "null" } ] } }, "required": [ "id", "kind", "url", "filename", "title", "rules", "scope", "status", "status_reason", "warning", "incomplete_pages", "pages", "passages", "characters", "size_bytes", "content_sha256", "file_sha256", "used_in_replies", "rules_fit", "rules_note", "created_at", "updated_at", "fetched_at" ] }, "ApiKnowledgeUploadRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file — PDF, Word (.docx), plain text, Markdown or CSV, up to the size this operation states. It is read to the end; a long one is cut into passages, not cut short." }, "title": { "description": "What to call it on the Developer screen and in a reply’s `sources`.", "type": "string" } }, "required": [ "file" ] }, "ApiListChannelsResponse": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The channel’s id: the `channel_id` every message sent to it names." }, "name": { "type": "string", "description": "Its name on every SlyOS screen." }, "system": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The system behind it, if you named one." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The environment of the key that made the call: `sandbox` or `live`." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "receive", "send", "attachments", "read_receipts", "mark_read", "delivery_receipts", "reactions", "typing", "threading", "groups" ] }, "description": "What the adapter declared it can do." }, "paused": { "type": "boolean", "description": "Whether the account owner has paused the channel." }, "auto_draft": { "type": "boolean", "description": "The channel’s automatic-drafting setting, as the owner last saved it." }, "last_inbound_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When a message last arrived on it." }, { "type": "null" } ] }, "last_outbound_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When a delivery was last reported on it." }, { "type": "null" } ] } }, "required": [ "id", "name", "system", "environment", "capabilities", "paused", "auto_draft", "last_inbound_at", "last_outbound_at" ] }, "description": "Every custom channel in the key’s environment." }, "known_capabilities": { "type": "array", "items": { "type": "string", "enum": [ "receive", "send", "attachments", "read_receipts", "mark_read", "delivery_receipts", "reactions", "typing", "threading", "groups" ] }, "description": "Every capability an adapter may declare." } }, "required": [ "channels", "known_capabilities" ] }, "ApiListKnowledgeResponse": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The source’s id." }, "kind": { "type": "string", "enum": [ "link", "site", "file" ], "description": "`link`: one page. `site`: a whole site, read from one address. `file`: an upload." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address it is read from. Null for a file." }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The uploaded file’s name. Null for a link or a site." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What it is called on the Developer screen and in a reply’s `sources`." }, "rules": { "type": "boolean", "description": "True when replies must follow it; false when it is reference material." }, "scope": { "type": "string", "enum": [ "project", "account" ], "description": "`project`: replies asked for with this key’s project use it. `account`: replies in every project on the account do." }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ], "description": "`queued`, then `processing`, while it is read in the background; `ready` once replies use it; `failed` when it could not be read, with `status_reason` saying why." }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "In a sentence, why the status is what it is. Null when there is nothing to say." }, "warning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the source is `ready` but some of what it shows may be missing, in a sentence naming the pages and what to do — today, pages that build their content with JavaScript, which SlyOS does not run (a price list drawn from a script, a template filled in after the page loads). Null when there is nothing to warn about." }, "incomplete_pages": { "type": "array", "items": { "type": "string" }, "description": "The addresses of the pages `warning` names: pages whose content is built with JavaScript, so replies may be missing what a visitor sees there. Add that text as a file, or as a single link to a page that shows it. Empty when there are none." }, "pages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Pages read from it." }, "passages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Passages it was cut into: what a reply retrieves from." }, "characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Characters of text read from it." }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The uploaded file’s size. Null for a link or a site." }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the text read from it; it changes when a refresh reads something new." }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the uploaded file’s bytes. Null for a link or a site." }, "used_in_replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many replies have relied on a passage of it." }, "rules_fit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "For a rules source: true when every one of the business’s rules reaches every reply; false when they no longer fit in one reply, and each reply gets the rules nearest its message. Null for reference material, or when it was not measured." }, "rules_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When `rules_fit` is false, in a sentence: how much the rules come to, what one reply carries, and what to do about it." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was added." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it last changed." }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was last read. Null until it has been." }, { "type": "null" } ] } }, "required": [ "id", "kind", "url", "filename", "title", "rules", "scope", "status", "status_reason", "warning", "incomplete_pages", "pages", "passages", "characters", "size_bytes", "content_sha256", "file_sha256", "used_in_replies", "rules_fit", "rules_note", "created_at", "updated_at", "fetched_at" ] }, "description": "Every source this key’s replies use: its project’s and the account’s." } }, "required": [ "sources" ] }, "ApiReadDraftResponse": { "type": "object", "properties": { "draft_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The draft’s id." }, "card_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The card the reply is for." }, "body": { "type": "string", "description": "The reply text." }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Which draft this is on the card." }, "model": { "type": "string", "description": "The model that wrote it." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When it was written." }, "held_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when SlyOS’s checks held this reply for a person — money, health or dosing, a legal or data-protection matter, another sensitive subject, or something it gives out that the account has not sent before. Never send a held reply automatically: show it to a person first. Null when SlyOS can no longer say, because the conversation has had a newer reply since; null means held. Send automatically only on `false`." }, "hold_reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Which check held it: `sensitive` (money, legal, health or credentials), `attachment` (it carries a file), `group` (it goes to a group), `regex_floor` (it matches a rule you set), `outbound_screen` (it gives out something not sent before, or answers a risky request). A code not listed here is still a hold — treat every code you do not recognise as one." }, "label": { "type": "string", "description": "The same reason in words, as the SlyOS inbox shows it." } }, "required": [ "code", "label" ] }, "description": "Why it was held: one entry per check that held it. Empty when `held_for_review` is not `true`." }, "hold_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the checks found, in sentences, when the reply was held. Null when it was not held, or when SlyOS cannot say." }, "superseded": { "type": "boolean", "description": "True when a newer reply has since been written on the same card. Send the newest, not this one." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The knowledge source the passage came from. Null once that source is deleted." }, { "type": "null" } ] }, "passage_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The passage itself. Null once its source is deleted." }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the source was called when the reply was written: its title, file name or address." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The page the passage was read from, for a link or a site." }, "page": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The page of the file its own text starts on, for a file that has pages. With `page_end`, the range it covers." }, "page_end": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The last page it runs onto, when it runs past `page` — a passage starting on page 11 and carrying page 12 is `page: 11, page_end: 12` (p.11–12). Null when it stays on one page, or the file has no pages." }, "section": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The heading it sat under, if any." }, "rule": { "type": "boolean", "description": "True for a binding rule the reply had to follow; false for reference material it could draw on." }, "rank": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Its place in what the reply was given, from 1 — counted separately for rules and for reference." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How close the passage was to the message, as cosine similarity. Null when there was nothing to compare." }, "excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Up to 280 characters of the passage’s OWN text — past the lines it repeats from the passage before it — from the sentence that shares the most words with the reply, else from its start; `…` marks a cut. While its source still exists." }, "text_sha256": { "type": "string", "description": "SHA-256 of the stored passage the reply was given — all of it, or its first `carried_chars` characters: proof of which text it relied on, even after the source changes." }, "carried_chars": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How many of the passage’s characters the reply was given, when it was cut to fit. Null when it was given the whole passage." } }, "required": [ "source_id", "passage_id", "title", "url", "page", "page_end", "section", "rule", "rank", "score", "excerpt", "text_sha256", "carried_chars" ] }, "description": "What this reply relied on: every passage of the business’s own knowledge — the links, sites and files it handed SlyOS, and its rules — that the reply was given, rules first. Empty when the reply was given none: the business has handed SlyOS nothing yet, or nothing it handed over matched." } }, "required": [ "draft_id", "card_id", "body", "generation", "model", "created_at", "held_for_review", "hold_reasons", "hold_detail", "superseded", "sources" ] }, "ApiRefusal": { "type": "object", "properties": { "code": { "type": "string", "description": "A stable code to branch on." }, "message": { "type": "string", "description": "One sentence, written for a person." } }, "required": [ "code", "message" ] }, "ApiSandboxDailyLimit": { "type": "object", "properties": { "code": { "type": "string", "const": "sandbox_daily_limit", "description": "Always `sandbox_daily_limit`." }, "message": { "type": "string", "description": "One sentence, written for a person." }, "used_today": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Sandbox drafts this account had in the last 24 hours." }, "daily_limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "What sandbox allows in any 24 hours." } }, "required": [ "code", "message", "used_today", "daily_limit" ] }, "ApiSaveBusinessProfileRequest": { "type": "object", "properties": { "business_name": { "description": "The business’s name, as replies should give it.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "description": { "description": "What the business is and does, in your own words: what it sells, who it serves, what it will and will not do.", "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "tone_notes": { "description": "How replies should sound — formal or warm, how to sign off — on top of the voice SlyOS learns from your own replies.", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "use_personal_context": { "description": "Accepted only when it equals the stored value, so the object `GET` returns can be sent back. A key that tries to change it, either way, is refused: only the account owner can, on the Developer screen.", "type": "boolean" }, "updated_at": { "description": "Accepted and ignored, so the object `GET` returns can be sent back.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "ApiUpdateKnowledgeRequest": { "type": "object", "properties": { "rules": { "description": "True to make it a binding rule; false to make it reference material.", "type": "boolean" }, "title": { "description": "A new name for it; null to go back to the name it was read with.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] } } }, "ApiUsageResponse": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The key’s environment, and the only one counted: a live key reads its project’s live usage, a sandbox key its sandbox drafts at nought cents." }, "window_days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How many days back the totals cover." }, "responses": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Billable responses charged in the window. Sandbox responses are never billable." }, "charged_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "What those responses cost, in total." }, "price": { "type": "object", "properties": { "version": { "type": "string", "description": "Today’s price version." }, "cents_per_response": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Today’s price for one successful response." } }, "required": [ "version", "cents_per_response" ], "description": "The price in force now." } }, "required": [ "environment", "window_days", "responses", "charged_cents", "price" ] }, "ApiWalletResponse": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The key’s environment. A sandbox key reads no money — every amount is 0 — and the drafts sandbox still allows today." }, "balance_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Money in the wallet. Always 0 for a sandbox key." }, "reserved_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Held for replies being written right now." }, "available_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "What can be spent: balance minus reserved." }, "responses_remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many more replies the available balance pays for at today’s price. For a sandbox key, how many sandbox drafts remain in the last 24 hours’ allowance." }, "sandbox_daily_limit": { "description": "Sandbox keys only: the drafts sandbox allows in any 24 hours (50).", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "environment", "balance_cents", "reserved_cents", "available_cents", "responses_remaining" ] }, "DraftReadyEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event’s own id. A retry of the same event carries the same id: deduplicate on it." }, "type": { "type": "string", "const": "draft.ready", "description": "The event type." }, "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "When the event happened, in Unix seconds — the same on every retry, so an old event reads as old." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "Which of the account’s two endpoints it was sent to: `sandbox` or `live`." }, "data": { "type": "object", "properties": { "draft_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The draft that is ready. Read it with `GET /v1/developer/drafts/{draftId}`." }, "card_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The card it is for." }, "generation_id": { "type": "string", "description": "The `generation_id` you asked for it with." }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Which draft this is on the card: 1 for the first, higher after another." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The environment of the key that made the call: `sandbox` or `live`." }, "held_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when SlyOS’s checks held this reply for a person — money, health or dosing, a legal or data-protection matter, another sensitive subject, or something it gives out that the account has not sent before. Never send a held reply automatically: show it to a person first. Null when SlyOS can no longer say, because the conversation has had a newer reply since; null means held. Send automatically only on `false`." }, "hold_reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Which check held it: `sensitive` (money, legal, health or credentials), `attachment` (it carries a file), `group` (it goes to a group), `regex_floor` (it matches a rule you set), `outbound_screen` (it gives out something not sent before, or answers a risky request). A code not listed here is still a hold — treat every code you do not recognise as one." }, "label": { "type": "string", "description": "The same reason in words, as the SlyOS inbox shows it." } }, "required": [ "code", "label" ] }, "description": "Why it was held: one entry per check that held it. Empty when `held_for_review` is not `true`." }, "hold_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the checks found, in sentences, when the reply was held. Null when it was not held, or when SlyOS cannot say." } }, "required": [ "draft_id", "card_id", "generation_id", "generation", "environment", "held_for_review", "hold_reasons", "hold_detail" ], "description": "What is ready." } }, "required": [ "id", "type", "created", "environment", "data" ] }, "WebhookTestEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event’s own id. A retry of the same event carries the same id: deduplicate on it." }, "type": { "type": "string", "const": "webhook.test", "description": "The event type." }, "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "When the event happened, in Unix seconds — the same on every retry, so an old event reads as old." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "Which of the account’s two endpoints it was sent to: `sandbox` or `live`." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "A sentence saying it is a test." } }, "required": [ "message" ], "description": "Nothing but the sentence." } }, "required": [ "id", "type", "created", "environment", "data" ] } } } }