Skip to main content
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 is usually the better fit; the full request and response schemas are in the OpenAPI reference.

​
Chat

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. 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).

​
Conversations

Sharing, rooms and mentions are covered in Shared rooms.

​
Your preferences

GET /user-preferences returns your language and display preferences:
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). 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).
  • 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.