Service API — integrating the platform

The whole web UI runs on an HTTP + SSE API you can call from your own systems. Base: https://<your-domain>/api/v1 (dev: http://localhost:4040/api/v1).

1. Authentication (JWT)

curl -X POST $BASE/api/v1/auth/register -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'

curl -X POST $BASE/api/v1/auth/login -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'   # → { access_token, refresh_token }

Then send Authorization: Bearer <access_token> on every call; refresh with the refresh_token.

1b. Personal API keys (recommended for integrations)

Instead of using your password, create an API key: Settings → 🔑 API keys → "New key". The key (sk_live_...) is shown only once — copy it immediately. Up to 20 active keys; revoke anytime from the same page.

# exchange the key for a short-lived access token (15 min)
TOKEN=$(curl -s -X POST $BASE/api/v1/auth/token -H "X-API-Key: sk_live_..." | jq -r .access_token)
# then call any endpoint
curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOKEN" ...

Only the key's hash is stored server-side. Revoking a key immediately blocks new exchanges; an already-issued token expires within 15 minutes. Usage is billed to your normal balance.

2. Talking to an agent (chat)

curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOK" -H 'content-type: application/json' -d '{
  "message": "Review this contract and list the risks",
  "app_name": "contract_review_dz",
  "attachments": ["<upload_id>"],
  "kb_ids": ["<kb_id>"]
}'
# → { "run_id": "…", "session_id": "…", "cursor": 0 }

• app_name — the target agent: any catalogue agent (interactive, data_copilot, slide_master…) or a custom agent built in the Agentic Studio: custom_<id>.
• attachments — file ids from POST /api/v1/uploads ({filename, content_base64, mime}).
• kb_ids — query an agent WITH your knowledge bases: the agent runs RAG over those workspaces during the conversation.
• session_id — reuse it for a multi-turn thread.

3. Streaming the answer (SSE)

curl -N $BASE/api/v1/runs/$RUN_ID/events -H "Authorization: Bearer $TOK"

event	payload
token	answer text fragment
tool_call / tool_result	the agent uses a tool ({"name": …})
plan / plan_step	live execution plan + progress
document_start/delta/end	a document being written in stream (artifact at the end)
chart	an interactive chart (JSON data)
file / artifact	a produced file (PPTX, XLSX, PDF…) → GET /api/v1/artifacts/{id}
usage / done / error	token counts, completion, error

The stream is resumable: send Last-Event-ID (or ?after=<cursor>) after a disconnect.

4. Querying a workspace (knowledge base) directly

curl -N -X POST $BASE/api/v1/kb/query/stream -H "Authorization: Bearer $TOK" \
 -H 'content-type: application/json' -d '{
  "kb_id":"<kb_id>", "q":"which termination clauses?",
  "enhance": true, "mode": "auto", "cite": true
}'

Modes auto · quick · full · deep · graph_local · graph_global, agent: true decomposition, [N] citations, extracted figures, per-query cost. Full details: Knowledge bases.

5. Embeddable widget (public chatbot on YOUR site)

Create a widget in Integrations → Widget, then paste:

<script src="https://<domain>/embed.js" data-widget="<widget_key>" defer></script>

The widget talks to /embed-api/* (public key + origin control); conversations are billed to your organisation.

6. Public sharing

• Shared KB: POST /api/v1/kb/{id}/share → /shared-kb/<slug> link, publicly queryable (billed to the owner).
• Documents / projects: equivalent share links (/shared-doc/<slug>).