Public API

The public API lets a third-party service embed an assistant. Authentication is by API key; calls are server-to-server JSON; identity is consumer-supplied. Use it to build a Q&A bot, an in-app chat, or any integration where you want the assistant's answer rather than the chat UI.

Shape of a request

One endpoint, one auth header, JSON in / JSON out. Each request runs exactly one assistant turn.

Client
Your server
method
POST
url
/assistants/:id/messages
auth
Bearer sk_live_…
Server
Assistant turn
user
externalUserId resolves
memory
loads relevant
model
Standard / Pro / Max
Reply
JSON body
sessionId
thread-789
reply
assistant text
model
gemini-3-flash-preview

When to use this

  • You're building a website or app and want "ask the assistant" without making every visitor sign up for sidanclaw.
  • You have your own user accounts and want each user's conversation memory to follow them.
  • You want full control over the chat UI (colors, branding, history, abuse mitigation).

When NOT to use this

  • Your users are signing up for sidanclaw anyway. The web chat is more featureful.
  • You need streaming output today. Synchronous JSON only in v1; SSE is on the roadmap.
  • You need the assistant to call third-party tools (Calendar, Gmail). API requests deliberately don't expose write-tools, because there's no human in the loop to approve confirmations.

Request flow

  1. 1Your backend receives a user message.
  2. 2POST /api/v1/assistants/{id}/messages with the message + your stable user id.
  3. 3sidanclaw resolves the user, runs the assistant turn, and returns the reply (3–15 s typical).
  4. 4Your frontend shows the reply.

Setup steps

  1. 1Sign in to sidanclaw, create the assistant you want to expose. Fill its knowledge base with anything the assistant should know.
  2. 2Open the assistant detail → API tab. Click "New key," name it (e.g. "production"), copy the plaintext shown. You won't see the secret again, so store it in your secret manager.
  3. 3Call POST /api/v1/assistants/{id}/messages from your backend. See the next pages for the wire format.