Gateway API

The SUPERWISE Chat gateway is 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). This page is the lookup reference for the endpoints you’ll use to build on Chat.

For how to authenticate, see Authentication. For end-to-end build walkthroughs, see Integrate. For inbound alert delivery, see Webhooks.

Base URL and conventions

All requests go to your SUPERWISE Chat base URL:

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

• Versioning — all product endpoints are under /v1. The OpenAI-compatible surface uses its own segment, /openai/v1.
• Content type — send Content-Type: application/json on every request with a body. Responses are JSON, except streaming chat and progress channels, which are text/event-stream.
• Request IDs — every request is tagged with an x-request-id (generated if you don’t supply one) and echoed back in error responses. Include it when reporting an issue.
• Tenant isolation — every request runs scoped to your tenant. You can only ever read or write your own tenant’s data; cross-tenant access returns 404.

Authentication at a glance

Pick the mechanism that matches the surface you’re calling. Full detail is in Authentication.

Surface	Header	Use it for
/v1/* product API	Authorization: Bearer <JWT>	Apps acting on behalf of a signed-in user
/v1/* (programmatic)	Authorization: Bearer swk_...	Server-to-server with a tenant API key
/openai/v1/*	Authorization: Bearer swk_...	OpenAI-compatible drop-in clients
/v1/embed/*	X-Embed-Key: <key>	The website chat widget
/v1/webhooks/{channel_id}	X-Webhook-Signature: <hmac>	Inbound monitoring alerts

Tenant API keys

API keys (swk_...) authenticate server-to-server calls and the OpenAI-compatible surface. Manage them under /v1/tenant/api-keys (requires the rbac.manage capability).

Method	Path	Notes
GET	/v1/tenant/api-keys	List keys (metadata only — never the secret)
POST	/v1/tenant/api-keys	Create a key; the full secret is returned once
DELETE	/v1/tenant/api-keys/{id}	Revoke a key

• Format: swk_<tenant-slug>_<random>. Create requires a non-empty scopes array; keys may carry an expires_at.
• The full secret is shown only at creation time — store it securely. Only a short prefix is retained afterward, so a lost key must be revoked and replaced.

Conversations and messaging

A conversation is a chat thread. Messages are sent into a conversation and the assistant’s reply streams back.

Method	Path	Purpose
POST	/v1/conversations	Create a conversation. Returns 201 with a Location header
GET	/v1/conversations	List conversations (keyset pagination; see below)
GET	/v1/conversations/{id}	Get one conversation
PATCH	/v1/conversations/{id}	Update title or tier
DELETE	/v1/conversations/{id}	Delete a conversation
GET	/v1/conversations/{id}/messages	List messages
POST	/v1/runtime/chat	Send a message and stream the reply (SSE)
PATCH	/v1/conversations/{id}/messages/{mid}	Edit a message (needs message.edit)
DELETE	/v1/conversations/{id}/messages/{mid}	Delete a message (needs message.delete)
GET	/v1/conversations/{id}/messages/{mid}/replies	List threaded replies (needs message.read)

Pagination

GET /v1/conversations uses keyset (cursor) pagination, not offset paging.

Query param	Meaning
limit	Items per page (default 50, max 100)
cursor	The last_activity_at timestamp of the last item from the previous page (ISO 8601). Omit for the first page

The response includes next_cursor; pass it back as cursor to fetch the next page. When next_cursor is null, you’ve reached the end.

{ "conversations": [ ... ], "limit": 50, "next_cursor": "2026-06-10T14:30:00.000Z" }

Send a message (streaming)

POST /v1/runtime/chat
Authorization: Bearer <JWT>
Content-Type: application/json
Accept: text/event-stream

{
  "conversation_id": "conv-abc123",
  "content": "What's our Q4 revenue target?",
  "tier": "QUICK"
}

tier is optional and selects how much reasoning the assistant applies, trading speed for depth:

tier	Best for
QUICK	Fast, single-pass answers
THINKING	The default — reasoning with search
RESEARCH	Deeper search, synthesis, and citations
THOUGHT_PARTNER	The full pipeline — search, reasoning, and tools

Omit tier to use the default (THINKING).

The response is an SSE stream. Each event has an event: line and a JSON data: line.

event: assistant_message
data: {"message_id":"msg-123","content":"Our Q4 revenue target is..."}

event: search_transparency
data: {"query":"Q4 revenue","sources":[ ... ]}

event: done
data: {"message_id":"msg-123","block_count":2}

Event types

Event	Meaning
assistant_message	A chunk or full assistant message
thinking_step / thinking_complete	Progress while the assistant reasons
execution_trace	Per-phase timing breakdown
phase_latency	Latency of a single pipeline phase
search_transparency	What sources the assistant looked at
swtoken_update	Usage update for the request
memory_proposal	A suggestion to remember a fact
guardrail_result	The outcome of a trust check
metadata	Request metadata
preflight_warning	A non-fatal heads-up (e.g. a fallback was used)
done	The stream completed successfully

Control / error events: interrupted, error, token_expired, stream_expired, reconnect.

Response block types (inside an assistant message): text, code, table, list, citation, image, vega, memory_proposal, knowledge_proposal.

Tip

SSE responses are not compressed, so they aren’t buffered. Streaming requests have a 60-second timeout (vs. 30 seconds for regular requests). If a stream is interrupted, the reconnect event tells your client it can resume.

Knowledge, memory, and notes

Method	Path	Purpose
GET / POST	/v1/knowledge/collections	List or create collections (create needs knowledge.create)
POST	/v1/knowledge/collections/{id}/promote	Promote a message into a collection
GET	/v1/knowledge/search?q=	Search knowledge manually
GET / POST	/v1/memories	List or create memories (with scope and category)
GET / PATCH / DELETE	/v1/memories/{id}	Read, update, or delete a memory
*	/v1/notes	Personal notes CRUD

Knowledge is also searched automatically while the assistant answers, so you rarely need to call search yourself.

Personas, workspaces, templates, feedback

Group	Path	Notes
Personas	/v1/personas	CRUD plus POST /{id}/publish; visibility private / team / org / public
Folders	/v1/folders	The current workspace surface
Projects	/v1/projects	Deprecated alias for folders. GET requests redirect (301); responses carry Deprecation and Sunset headers. Use folders for new work
Templates	/v1/templates	Reusable prompts; GET /v1/templates/search?q=. Built-in system templates can’t be edited
Feedback	/v1/feedback	Thumbs up/down on a response. The query text is hashed before storage, never stored raw

Identity and permissions

Method	Path	Purpose
GET	/v1/me	The current user’s identity, read straight from the token
GET	/v1/receptor	The server-evaluated view of what this user can see and do
GET	/v1/rbac/me	The user’s roles and computed permissions
GET	/v1/roles, /v1/groups, /v1/permissions	Read role, group, and permission data

Always fetch permissions, never assume them

/v1/receptor returns the authoritative permission and visibility model for the signed-in user. Your UI should fetch it and gate features off the result, rather than guessing permissions client-side. The server is the source of truth.

Sharing a conversation

Method	Path	Purpose
POST / GET / DELETE	/v1/chat/{id}/share[/{user_id}]	Share with a user (READ / WRITE), list grants, or revoke
POST	/v1/chat/{id}/share-link	Create a time-limited public link (1h / 24h / 7d / 30d)
GET / DELETE	/v1/chat/{id}/share-link[s]/{link_id}	List or revoke links by link_id
GET	/v1/shared/{token}	View a shared conversation (no auth — see below)

When you create a public link, the response includes both a token (returned once, used in the public URL) and a link_id (the stable handle you use to revoke it). The raw token is never stored on the server.

Public (no authentication) endpoints

A small set of endpoints are intentionally open:

Endpoint	Purpose
GET /health	Liveness and readiness
GET /v1/config/feature-flags	Front-end bootstrap flags
GET /v1/shared/{token}	View a shared conversation; 410 Gone if the link is revoked or expired. Rate-limited to 30 req/min
GET /v1/consent/activities	GDPR Article 13 consent activities

Trust and governance endpoints

Chat applies trust checks while answering and records every action for review. Most governance endpoints are admin-scoped; the developer-facing ones are below.

Method	Path	Purpose
GET / POST	/v1/approvals	List or request an approval. Types: tool_execution, export, share, data_access. Risk levels: low / medium / high / critical
GET	/v1/approvals/{id}	Get an approval request
POST	/v1/approvals/{id}/decide	Approve, deny, or edit a pending request
POST	/v1/approvals/{id}/cancel	Cancel a request you made
GET	/v1/policy	The tenant’s active policy (banner, classification, retention, export rules)

When an action needs sign-off, the API returns the approval request instead of performing the action — once approved, the action proceeds. This keeps sensitive operations under human review without breaking your integration flow.

External integration surfaces

Embed widget

The website chat widget authenticates with a per-tenant embed key.

Method	Path	Auth	Notes
POST	/v1/embed/sessions	X-Embed-Key	Start or resume a widget session. Requires an Idempotency-Key header
GET	/v1/embed/sessions/{id}	X-Embed-Key	Check session status

These routes are CORS-open because they’re called from customer websites. An invalid or revoked key returns 401.

OpenAI-compatible API

A drop-in surface for clients built against the OpenAI Chat Completions shape.

Method	Path	Auth	Notes
POST	/openai/v1/chat/completions	swk_... API key	Standard chat completions request/response shape
GET	/openai/v1/models	swk_... API key	List available models

Point an OpenAI-compatible SDK at the base URL https://api.superwise-chat.company.com/openai/v1 and use a tenant API key as the bearer token. No Idempotency-Key is required. Errors on this surface use the OpenAI error shape ({ "error": { "message", "type", "code" } }) rather than the standard gateway error format. This surface has its own rate limit, separate from the /v1 limit.

Rate limits

Surface	Limit
/v1/* (default)	~60 requests/min per tenant
/v1/shared/{token}	30 requests/min
/openai/v1/*	Its own per-API-key limit
/health	A looser dedicated limit

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch seconds). When you exceed the limit you get a 429 — back off until the reset time. Tenants can have per-tenant overrides, so treat the headers on your own responses as authoritative rather than hard-coding a number.

Errors

The gateway returns errors in RFC 9457 problem+json:

{
  "type": "not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No route matches GET /v1/conversations/missing",
  "request_id": "1a2b3c..."
}

Some endpoints return a simpler { "error", "message" } shape, and validation failures add an errors array listing each problem. Always read status for the outcome and request_id for support.

Status	Meaning
400	Bad request or validation failure
401	Missing or invalid credentials
403	Authenticated, but not allowed
404	Not found, or it belongs to another tenant
409	Conflict (e.g. a duplicate name or already-registered channel)
410	Gone (a revoked/expired share link, or a removed legacy endpoint)
422	The request body is structurally invalid
429	Rate limited
500	Unexpected server error

Quick start

# 1. Create a conversation
curl -X POST https://api.superwise-chat.company.com/v1/conversations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My first conversation"}'

# 2. Send a message and stream the reply
curl -N -X POST https://api.superwise-chat.company.com/v1/runtime/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"conversation_id": "conv-abc123", "content": "What is our Q4 revenue target?"}'

Related pages

• Authentication — tokens, API keys, and embed keys in depth
• Integrate — build a working integration step by step
• Webhooks — receive monitoring alerts into a conversation