Integration guide

This is the entry point for integrating SUPERWISE Chat with your applications. It maps the available integration surfaces to the credential each one needs, lists the base URLs and conventions every call shares, and points you to the detailed reference for each path.

SUPERWISE Chat exposes a JSON REST API. Every product endpoint lives under the /v1 prefix, accepts and returns JSON, and streams chat responses over Server-Sent Events (SSE). For authentication detail see Authentication; for the full endpoint reference see the Gateway API; for inbound alert delivery see Webhooks.

Choose your integration surface

Pick the surface that matches what you are building. Each one has a distinct base path, credential, and behavior.

Surface	Use it to	Base path	Credential
Gateway API	Build a full app on Chat — conversations, knowledge, memory, notes, personas, governance	/v1/*	User JWT, or a tenant API key (swk_*) for server-to-server
OpenAI-compatible API	Drop SUPERWISE Chat into existing OpenAI client code	/openai/v1/*	Tenant API key (swk_*)
Embed widget	Add a chat bubble to a public website	/v1/embed/*	Embed key (X-Embed-Key)
Inbound webhooks	Route monitoring/alerting events into a conversation	/v1/webhooks/*	Per-channel HMAC signature

Just want chat completions?

If you already have code written against the OpenAI API, start with the OpenAI-compatible API below — it is the smallest change. Reach for the full Gateway API when you need conversations, knowledge, memory, or governance.

Base URL and conventions

All requests go to your SUPERWISE Chat base URL:

https://api.superwise-chat.company.com

Convention	Detail
Versioning	Product endpoints are mounted under /v1. There is no /v2. The OpenAI-compatible surface carries its own version segment at /openai/v1.
Wire format	JSON in, JSON out. Streaming chat and progress channels use SSE (text/event-stream).
Request IDs	Every request is tagged with an x-request-id (generated if you don’t send one) and echoed back in error responses — include it when contacting support.
Errors	Framework-level errors use RFC 9457 problem+json (type, title, status, detail, request_id). Some handlers return a flat { error, message }. Both are documented in the Gateway API.

Authentication at a glance

Which credential you send depends on the surface you call. Full detail, including how to mint and revoke each one, is in Authentication.

Credential	Header	Surfaces	Notes
User JWT	Authorization: Bearer <JWT>	/v1/*	Per-user identity; carries tenant and roles. Used by your frontend on behalf of a signed-in user.
Tenant API key	Authorization: Bearer swk_...	/openai/v1/*, server-to-server	Format swk_<tenant-slug>_<hex>. Shown in full once at creation — store it securely. Scoped, optionally expiring, revocable.
Embed key	X-Embed-Key: <key>	/v1/embed/*	Per-tenant public widget key, safe to ship in browser code.
Webhook HMAC	X-Webhook-Signature: <hmac-sha256-hex>	POST /v1/webhooks/{channel_id}	Computed over the raw request body with the per-channel secret.

Keep secrets server-side

Tenant API keys (swk_*) and webhook secrets grant programmatic access and must never be exposed in browser code or committed to source control. Only the embed key is designed to be public. A leaked tenant key should be revoked immediately and re-issued.

Quick start: OpenAI-compatible API

If you have an existing OpenAI integration, point it at SUPERWISE Chat by changing two things: the base URL and the API key.

1. Create a tenant API key. An admin creates one under your tenant’s API key settings (it requires the key-management capability). Copy the swk_... value when it is shown — it is not retrievable later.

2. Set your client’s base URL to https://api.superwise-chat.company.com/openai/v1.

3. Send a chat completion:

   curl https://api.superwise-chat.company.com/openai/v1/chat/completions \
     -H "Authorization: Bearer swk_yourtenant_xxxxxxxx..." \
     -H "Content-Type: application/json" \
     -d '{
       "model": "default",
       "messages": [{"role": "user", "content": "Hello"}]
     }'

4. List available models with GET /openai/v1/models.

The request and response shapes follow the OpenAI format, and errors use the OpenAI { "error": { "message", "type", "code" } } shape. This surface has its own per-key rate limit (separate from the /v1 umbrella) and does not require an Idempotency-Key.

Quick start: Gateway API

Use the full Gateway API when you need conversations, streaming, knowledge, memory, or governance. A typical first call sequence:

1. Obtain a user JWT from your identity provider and confirm identity with GET /v1/me.
2. Create a conversation with POST /v1/conversations.
3. Send a message and stream the reply with POST /v1/runtime/chat and Accept: text/event-stream. The body is { "conversation_id", "content", "tier" }, where tier is one of QUICK, THINKING, or THOUGHT_PARTNER.
4. List history with GET /v1/conversations/{id}/messages.

See the Gateway API for the full endpoint catalog and field-level shapes.

Streaming responses (SSE)

POST /v1/runtime/chat returns a Server-Sent Events stream rather than a single JSON body.

Property	Value
Request header	Accept: text/event-stream
Stream timeout	60 seconds (regular requests time out at 30 seconds)
Frame format	An event: line naming the event type, followed by a data: line with a JSON payload

Event types you will receive include assistant_message, thinking_step, thinking_complete, search_transparency, memory_proposal, metadata, and done. Control events include interrupted, error, token_expired, stream_expired, and reconnect. Assistant content arrives as typed blocks — text, code, table, list, citation, image, and vega (charts) among them — so you can render rich replies rather than plain strings.

Handle reconnection

If your client receives a token_expired, stream_expired, or reconnect event, refresh the credential if needed and re-issue the request. Build retry/resume into your streaming client from the start.

Embed the chat widget

To add a chat bubble to a public website, use the embed surface with an embed key.

Method	Path	Purpose
POST	/v1/embed/sessions	Create a widget session (requires an Idempotency-Key header)
GET	/v1/embed/sessions/{id}	Resume an existing widget session

The embed surface is CORS-open so it can be called directly from customer websites, and it authenticates with the per-tenant X-Embed-Key header. An invalid or revoked key returns 401.

Inbound webhooks

Webhooks in SUPERWISE Chat are inbound: your monitoring and alerting tools POST event payloads to a channel you register, and the alert is delivered into a conversation. Supported providers are PagerDuty, Datadog, and a generic Custom format.

1. Register a channel with POST /v1/webhooks/register (requires a JWT and the webhook management capability). The HMAC secret is returned once — store it.
2. Send alerts to POST /v1/webhooks/{channel_id} with an X-Webhook-Signature: <hmac-sha256-hex> header computed over the raw body using that secret.
3. Check status with GET /v1/webhooks/{channel_id}/info.

Full setup, signing details, and payload handling are in Webhooks.

Rate limits

Surface	Limit	Notes
/v1/* (product API)	Per-tenant umbrella limit	Returns 429 when exceeded
/openai/v1/*	Per-API-key limit	Independent of the /v1 umbrella
/v1/webhooks/*	Dedicated webhook limit	Tuned for alert ingest
Public shared-conversation view	30 requests/minute	Per shared link

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (an epoch-seconds timestamp). On a 429, back off until X-RateLimit-Reset. Specific limit values are per-deployment — read the live response headers rather than hard-coding a number.

Error handling

Common status codes across all surfaces:

Status	Meaning	What to do
400	Bad request or validation failure	Check the detail / errors[] in the response
401	Missing or invalid credential	Refresh the JWT, key, or signature
403	Lacking the required permission	The credential is valid but not authorized for this action
404	Not found (or belongs to another tenant)	Verify the ID and that the credential’s tenant owns it
409	Conflict (e.g. duplicate channel)	The resource already exists
410	Gone (revoked/expired link, removed endpoint)	Re-create the resource or update the path
429	Rate limited	Back off until X-RateLimit-Reset
500	Unexpected server error	Retry with backoff; include x-request-id if you contact support

Next steps

• Authentication — mint, scope, and revoke each credential type.
• Gateway API — the full endpoint reference with request and response shapes.
• Webhooks — register channels and sign inbound alert payloads.