API reference

Base https://ai.syctra.com/api/v1 · every endpoint needs Authorization: Bearer <token> unless marked public. See API & native integration for authentication, errors, limits and security.

Runs — talk to an agent

POST /chat

Starts a durable run and returns immediately.

Field	Type	Default	Description
message	string	—	Required. What you ask the agent
app_name	string	"main"	Target agent. Any catalogue key (interactive, data_copilot, contract_review_dz, slide_master, finance_master…) or custom_<id> for one of your own
session_id	uuid	new	Continue an existing thread. Omit to start one
attachments	string[]	—	Upload ids from POST /uploads
kb_ids	string[]	—	Knowledge bases the agent may search during the run
kb_enhance	bool	false	LLM-rewrite RAG answers (slower, richer)
plan	bool	false	Plan mode: the agent writes a step plan and executes it, emitting plan / plan_step
model	string	account default	Model catalogue key — see GET /models
reasoning	bool	false	Longer deliberation before answering
data_workspace_id	uuid	—	Data Lab workspace the agent should work on
client_tz	string	UTC	IANA timezone, e.g. "Africa/Algiers"
idempotency_key	string	—	Replay-safe: the same key returns the same run

{ "run_id": "…", "session_id": "…", "cursor": 0, "resumed": false,
  "status": "running", "queue_seq": 0 }

status is running, or queued when the session is busy (the run starts automatically when the one before it finishes), or blocked.

Method	Path	Purpose
POST	/tasks	Same as /chat but explicitly detached — for background jobs
GET	/runs/{run_id}/events	SSE stream of the run (below)
POST	/runs/{run_id}/respond	Answer a question the agent asked (user_choice, quiz, approval)
POST	/runs/{run_id}/cancel	Stop a running run
GET	/sessions/{id}/queue	Inspect the session's pending queue
POST	/sessions/{id}/queue/resume	Resume a queue paused by a failure

GET /runs/{run_id}/events — the stream

text/event-stream. Each event carries id (a monotonic seq), event (its type) and data (JSON). Resumable: reconnect with Last-Event-ID: <seq> or ?after=<seq> and everything after that cursor is replayed from durable storage — no work is lost and nothing is billed twice.

Group	Events
Answer	token (text fragment) · usage (token counts) · done · error
Tools	tool_call · tool_result · sandbox_stdout
Plan	plan (ordered steps) · plan_step (index + status)
Documents	document_start · document_delta · document_end (carries artifact_id)
Deliverables	artifact · file (PDF/DOCX/PPTX/XLSX) · image · slides · webpage · chart · sheet
Research	sources (web results) · graph (knowledge graph) · browser (computer-use screenshots) · maps
Human in the loop	user_choice · choice_answer · quiz · approval (action awaiting your confirmation)
Communication	email_draft · email_sent · social · call
Legal studios	dossier · timeline · doc_summary · findings · contract · clause · contract_compare · consultation · legal_issues · ref_check · deadline · watch_synthesis · watch_change · watch_diff
Recruitment	candidate · iv_job · iv_candidate · iv_questions · iv_grid · iv_answers · iv_ask · iv_plan
Business	prospect · cerfa · exhibition · finance · site_map · site_pack

Consume token, done and error for a plain text answer; the rest are structured cards you can render or ignore. Unknown event types must be skipped, not treated as errors — new ones are added over time.

Method	Path	Purpose
GET	/models	Model catalogue available to your account
GET	/sessions	List conversations
GET	/sessions/{id}	One session + its recent events
PATCH DELETE	/sessions/{id}	Rename / delete
GET	/sessions/{id}/messages	Full message history
GET	/sessions/{id}/artifacts	Everything the session produced
POST	/sessions/{id}/branch	Fork the conversation at a point
POST	/sessions/{id}/truncate	Cut the conversation back to a message
GET POST	/sessions/{id}/versions	Artifact version history / restore
GET	/sessions/search?q=	Full-text search across your conversations

Files

Method	Path	Purpose
POST	/uploads	{filename, content_base64, mime, session_id?} → {upload_id}. Parsed automatically (OCR, vision, transcription). Up to 200 MB per file
GET	/uploads/{id}	Parsing status and extracted text
GET	/uploads/{id}/raw	The original bytes
POST	/artifacts	Create an artifact from your own content
GET	/artifacts/{id}	Download a produced file
POST	/export	Render Markdown/HTML to PDF, DOCX or PPTX
POST	/export-text	Plain-text export

Attach an upload to a run by passing its id in attachments. Accepted: PDF, Office, images, audio, video, CSV/Excel, ZIP (recursively expanded).

Knowledge bases (RAG)

Method	Path	Purpose
POST GET	/kb	Create / list knowledge bases
PATCH DELETE	/kb/{id}	Rename / delete
GET POST	/kb/{id}/documents	List / add documents (ingestion is asynchronous)
POST	/kb/query/stream	Query, streamed (below)
GET PUT	/kb/{id}/config	Retrieval profile (legal / enterprise / timeline / generic), FTS language, budgets. PUT rewrites every field — send the full object
GET	/kb/{id}/chunks · /entities · /graph	Inspect the index, extracted entities, knowledge graph
GET	/kb/{id}/file/{doc_id} · /image/{image_id}	Source document / extracted image
POST GET	/kb/{id}/conversations	Multi-turn RAG threads
GET	/kb/{id}/conversations/{cid}/messages	Thread history
GET POST DELETE	/kb/{id}/connectors …	Sync from external sources; /kb/connectors/catalog lists them
POST GET DELETE	/kb/{id}/share	Publish a public query link
GET	/kb/pricing	Per-query cost model

curl -N -X POST https://ai.syctra.com/api/v1/kb/query/stream \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
    "kb_id": "…", "q": "Which termination clauses apply after 12 months?",
    "mode": "full", "cite": true, "enhance": false, "agent": false, "top_k": 20
  }'

Field	Values	Description
mode	auto · quick · full · deep · graph_local · graph_global	Retrieval depth. auto picks from the question
cite	bool	Inline [N] citations plus source ids
enhance	bool	LLM-rewrite the answer
agent	bool	Decompose multi-part questions before retrieving
doc_id	string	Restrict retrieval to a single document
conversation_id	uuid	Continue a multi-turn thread

Custom agents

Method	Path	Purpose
GET	/agent-tools	The capability catalogue you can toggle on an agent
GET POST	/agents/custom	List / create
GET PUT DELETE	/agents/custom/{id}	Read / update / delete
POST	/agents/custom/persona	Distil a persona from uploaded writing samples
GET	/marketplace · /marketplace/{id}	Published agents
POST	/marketplace/{id}/install · /publish · /unpublish	Install / publish / withdraw

{
  "name": "Tender analyst", "emoji": "📑",
  "description": "Reads tender files and produces a go / no-go note",
  "instruction": "You are a public-procurement analyst…",
  "tool_keys": ["web", "deep_research", "documents", "knowledge_base", "database"],
  "model": "standard", "visibility": "private",
  "examples": ["Analyse this tender"], "tags": ["procurement"]
}

Capability keys: knowledge_base · web · deep_research · agent_team · computer_use · algerian_law · documents · slides · charts · images · webpage · code · quiz · email · planning · scraping · prospecting · linkedin · meta · obsidian · knowledge_graph · scheduling · workspace_files · data_engineering · database · n8n · stripe · paypal · notion · github · gitlab · elevenlabs · microsoft · atlassian · slack · s3 · apify · mcp_remote.

Run it like any other agent: POST /chat with "app_name": "custom_<id>".

Scheduler

Method	Path	Purpose
GET POST	/cron	List / create a scheduled run
PATCH DELETE	/cron/{id}	Pause, edit, delete
POST	/cron/{id}/run	Trigger once, now

{ "name": "Monday competitor watch", "cron_expr": "0 8 * * 1",
  "timezone": "Africa/Algiers", "prompt": "Summarise last week's moves by…",
  "app_name": "main", "delivery_email": "team@acme.com" }

Standard 5-field cron. delivery_email mails the final answer; leave empty for none.

Data Lab

Method	Path	Purpose
GET POST	/data/workspaces	List / create a persistent DuckDB workspace
PATCH DELETE	/data/workspaces/{id}	Rename / delete
POST	/data/workspaces/{id}/ingest	Load Excel/CSV — messy sheets, multi-row headers, several tables per sheet
GET	/data/workspaces/{id}/tables · /files	Inspect the schema and sources
POST	/data/workspaces/{id}/query	Run SQL against the workspace
DELETE	/data/workspaces/{id}/tables/{table}	Drop a table

Agent swarm

Method	Path	Purpose
GET	/swarm/api/teams · /catalogue · /health	Available teams and engine status
POST	/swarm/api/run	Start a multi-agent run
GET	/swarm/api/run/{id}/stream	SSE progress
POST	/swarm/api/run/{id}/cancel	Stop it
GET	/swarm/api/dossiers · /{id} · /{id}/file/{name}	Produced dossiers and their files
POST	/swarm/api/convert · /template/inspect	Convert output / inspect a deck template

Documents & projects

Method	Path	Purpose
GET	/docspace	Folder tree + documents
POST PATCH DELETE	/folders, /folders/{id}	Manage folders
POST PATCH DELETE	/documents, /documents/{id}	Manage documents
GET	/documents/{id}/content	Read content
POST	/documents/{id}/attach	Attach a document to a conversation
POST	/docspace/import-zip	Bulk import
GET POST	/projects, /projects/{id}	Workspaces grouping conversations and files
POST GET DELETE	/projects/{id}/members	Project access

Sharing (public links)

Method	Path	Purpose
POST GET DELETE	/sessions/{id}/share	Publish a conversation
GET	/shared/{slug}	Public read of a shared conversation
GET	/shared/{slug}/artifacts/{id}	Public artifact from a shared conversation
GET POST	/shared/{slug}/comments	Public comment thread
POST	/shared/{slug}/clone	Copy a shared conversation into your account
POST GET DELETE	/docshare	Share documents / folders
GET	/shared-doc/{slug}	Public shared document
GET	/shared-kb/{slug} · POST /shared-kb/{slug}/query/stream	Public knowledge-base link, queries billed to the owner

Public links are unlisted URLs, not authentication. Anything you publish is readable by anyone holding the link — and queries against a shared knowledge base are billed to you. Revoke with the matching DELETE.

Embeddable widget

Create a widget under Integrations → Widget, then paste one line into your site:

<script src="https://ai.syctra.com/embed.js" data-key="pk_live_…" async></script>

Optional data-position="bottom-left" | "bottom-right". The widget calls a separate public API under /embed-api — the public key is not an API key and cannot read your account:

Method	Path	Purpose
GET	/embed-api/config/{public_key}	Public widget configuration
POST	/embed-api/chat	Public visitor message
GET	/embed-api/runs/{run_id}/events	Public answer stream
GET	/embed-api/history/{public_key}/{visitor_id}	Public visitor history
GET POST PATCH DELETE	/embed-widgets	Owner CRUD (authenticated)

The /embed-api/* and /scim/v2/* paths are served at the host root, not under /api/v1 — e.g. https://ai.syctra.com/embed-api/chat.

Only agents allow-listed for public use can be attached to a widget, visitor traffic is rate limited per widget, and every conversation is billed to the owning organisation. Restrict the allowed origins on the widget before publishing it.

Teams, organisation & provisioning

Method	Path	Purpose
GET	/enterprise · /enterprise/analytics · /enterprise/retention	Organisation, usage, retention policy
POST DELETE	/enterprise/teams, /teams/{id}	Manage teams
POST DELETE	/enterprise/teams/{id}/members…	Membership
POST DELETE	/enterprise/teams/{id}/grants	Which agents a team may use
POST	/enterprise/teams/{id}/invite · /invites/revoke · /invites/resend	Invitations
GET POST	/invite/{token}, /invite/{token}/accept	Public invitation acceptance
GET PUT DELETE	/enterprise/sso	SAML / OIDC single sign-on
POST	/enterprise/scim-token	Mint a SCIM provisioning token
GET	/me/caps · /me/teams · POST /me/active-team	The caller's rights and teams
GET POST DELETE	/teams, /groups, /share-targets	Lightweight teams, groups, sharing targets

SCIM 2.0 is served at https://ai.syctra.com/scim/v2 with its own token (not an API key): GET|POST /Users, GET|PUT|PATCH|DELETE /Users/{id}, GET /Groups.

Account, notifications & privacy

Method	Path	Purpose
GET PATCH	/auth/me	Profile
POST	/auth/change-password · /auth/logout	Credentials / sign out
GET	/balance	Credit balance
GET POST	/notifications, /notifications/read	In-app notification feed
PUT	/me/notify-email · /me/low-balance-pct	Notification preferences
GET POST	/push/vapid-key, /push/subscribe	Web-push subscriptions
GET DELETE PUT	/memory, /memory/{id}, /memory/settings	Long-term memory: read, delete, opt out
GET	/account/export	GDPR — export everything you own
DELETE	/account	GDPR — delete the account and its data
GET POST	/approvals, /approvals/{id}/decide	Approve or refuse a gated action
GET PUT	/approval-settings	Which capabilities require human approval

Other surfaces

Method	Path	Purpose
GET POST DELETE	/deadlines…	Legal deadline agenda
POST GET DELETE	/meetings…	Meeting transcription and minutes
POST GET DELETE	/dubbings…, GET /dubbing/languages	Video / audio dubbing jobs
POST GET DELETE	/email-compose, /email-templates	Composed e-mails and templates
POST	/email/send	Send an e-mail through the platform
GET POST DELETE	/prompts	Saved prompts
POST	/feedback · /message-feedback	Product and per-answer feedback
GET	/healthz · /readyz · /metrics	Public liveness, readiness, Prometheus metrics

Notes for integrators

• There are no outbound webhooks yet. Track long work by holding the SSE stream open, or by polling GET /sessions/{id} — a run survives your disconnection either way.
• Poll politely. Prefer SSE; if you must poll, use the cursor you already hold.
• Store the cursor. Persisting the last seq you processed makes your integration crash-safe.
• Pin the agent. app_name decides behaviour, cost and available tools — set it explicitly instead of relying on the main default.
• Handle 402 and 429 first. They are the two errors a healthy integration meets in production; everything else usually means a bug in the payload.