> ## Documentation Index > Fetch the complete documentation index at: https://docs.semicola.com/llms.txt > Use this file to discover all available pages before exploring further. # Semi API > Chat with Semi over REST: send a turn, stream it, decide confirmations, manage conversations, sharing and language, and inspect seller calls. Semi, the assistant in the app, is also reachable over REST at `/api/v2/assistant`. Use it to put Semi in your own interface. For agent-to-platform work, the [v3 MCP endpoint](/v3/overview) is usually the better fit; the full request and response schemas are in the OpenAPI reference. ## Chat | Endpoint | What it does | | ------------------------------------ | -------------------------------------------------------------------------------------------- | | `POST /chat` | Run one turn and return the full response. | | `POST /chat/stream` | Run one turn as server-sent events, ending with `done` or `error`. | | `POST /chat/stop` | Stop the running turn in a conversation (`conversationUid`). | | `POST /confirmations/{uid}/decision` | `confirm` or `cancel` a pending write (see [Semi confirmations](/setup/semi-confirmations)). | A chat request carries the `prompt` (up to 32,000 characters), the `scopeType` and `scopeId`, an optional `conversationUid` to continue a conversation, `attachments` (up to 5), an optional `preferredLanguage`, and `pageContext` (what the person is looking at). Upload attachments first with `POST /attachments`, which returns a signed upload URL. The response carries Semi's text, the tools it used, any pending confirmations, and a widget directive when a tool opened a page. Render widgets as described in [MCP Apps](/v3/mcp-apps). A dropped stream can resume: reconnect to `GET /conversations/{uid}/stream` with the `Last-Event-ID` header (or `after`) set to the last event you saw. ## Conversation scope Every conversation has a scope: the account (`scopeType: "customer"`, with the account id) or one advertiser (`scopeType: "advertiser"`). Set it when you create the conversation (`POST /conversations` with `scopeType`, `scopeId`, an optional `title` and `workspace`) or on the first chat turn. List conversations for a scope with `GET /conversations?scopeType=…&scopeId=…` (take/skip paging; see [Pagination](/v3/pagination)). ## Conversations | Endpoint | What it does | | ------------------------------------- | ------------------------------------------------------------ | | `GET /conversations/{uid}` | Messages, pending confirmations and the live widget. | | `PATCH /conversations/{uid}/title` | Rename (`title`, up to 200 characters). | | `PATCH /conversations/{uid}/sharing` | Turn sharing with teammates on or off (`sharingEnabled`). | | `PATCH /conversations/{uid}/language` | Set the conversation's language. | | `POST /conversations/{uid}/messages` | Post to Semi or, in a shared chat, to the room (`audience`). | | `GET /conversations/{uid}/events` | The conversation's event feed. | | `DELETE /conversations/{uid}` | Delete it. | Sharing, rooms and mentions are covered in [Shared rooms](/guides/shared-rooms). ## Your preferences `GET /user-preferences` returns your language and display preferences: ```json theme={null} { "preferredLanguage": "de", "locale": "de-DE", "timezone": null, "displayCurrency": null, "language": "de", "announcements": true, "defaultSharingEnabled": false } ``` | Field | Scope | Notes | | ----------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preferredLanguage` | You | Your default language, or `null` (Semi follows the language you write in). Codes below. | | `locale` | You | The BCP 47 display locale (`de-DE`, `ja-JP`): the one you signed up with, else your language's default (`fr` → `fr-FR`, `pt` → `pt-BR`, `zh` → `zh-CN`), else `null`. | | `timezone` | You | IANA time zone. Read-only; Semicola doesn't set it yet, so it's `null`. | | `displayCurrency` | You | ISO 4217 code. Read-only; Semicola doesn't set it yet, so it's `null`. Amounts always show in their record's own currency. | | `announcements` | The account | Semi announcements for the account (default `true`). See below. | | `defaultSharingEnabled` | The account | Whether new chats start shared. Admins only; anyone else gets `FORBIDDEN`. | | `language` | You | Deprecated: `preferredLanguage`, or `en` when that's `null`. | A request with a service token (no person) gets the same shape with `preferredLanguage`, `locale`, `timezone` and `displayCurrency` all `null`. **Set your language** with `PUT /user-preferences/language` and `{ "preferredLanguage": "fr" }`, or `{ "preferredLanguage": null }` to clear it. It answers with the full preferences now in effect. Setting a language also resets `locale` to that language's default. A service token can't set one (`BAD_REQUEST`: "Only people have a default language."). `PUT /user-preferences` takes `preferredLanguage`, `announcements` and `defaultSharingEnabled` together; the older `language` field is still accepted on both routes. Language codes: `en` English, `de` German, `fr` French, `es` Spanish, `pt` Portuguese, `it` Italian, `nl` Dutch, `sv` Swedish, `pl` Polish, `ja` Japanese, `ko` Korean, `zh` Chinese (Simplified), `ar` Arabic, `hi` Hindi, `tr` Turkish. Semi replies in any of them. The app's interface is translated into ten: English, German, Spanish, French, Italian, Japanese, Korean, Dutch, Brazilian Portuguese and Simplified Chinese; with the other five it stays in English (see [Language](/guides/the-app#language)). Your default applies to a new chat when the client sends it: the app sends it as `preferredLanguage` on a new chat's first turn, and a conversation keeps its own language after that (`PATCH /conversations/{uid}/language`). Over REST, pass `preferredLanguage` on the first `POST /chat` yourself: `POST /conversations` and a first turn without it don't read your default yet. ### Announcements Settings → **Semi preferences** has an **Announcements** card: "Occasional updates from Semicola, delivered by Semi in your Slack channel." Its switch, **Receive Semi announcements** ("Turn off to stop receiving broadcast updates from Semicola."), is the account's opt-in, on by default. Read and set it with `GET /announcement-preference` and `PUT /announcement-preference` (`{ "enabled": true }`), or through the `announcements` field of `/user-preferences`. Both answer with the same setting. Announcements are delivered only in the account's Slack channel. That needs Semicola's Slack app, which isn't registered yet, so no announcements are sent today; the opt-in is saved for when they are. ## Seller call debugging `GET /agent-debug-calls` (optionally `?campaignId=…`) shows, for the latest proposal request, what each seller's `get_products` call did: `outcome` (`returnedProducts`, `returnedNone`, `failed` or `notCalled`), `productCount`, `latencyMs`, `error`, and the request and response payloads. ## Other reads `GET /usage` (your assistant usage against its cap), `GET /starter-prompts`, `GET /digest` (unread items), `GET /mentionable-users` and `GET /health`. ## Not available yet * A separate account-wide conversation-settings endpoint: set the sharing default with `PUT /user-preferences` (`defaultSharingEnabled`). * Announcement delivery: it needs the Slack app (see [Announcements](#announcements)). * Rendering artifacts beyond widgets (for example a discovery card payload) and an `ask_semi` MCP tool. * Transport attempts and sandbox/live provenance on debug calls.