Référence API

Base https://ai.syctra.com/api/v1 · chaque endpoint exige Authorization: Bearer <token> sauf mention public. Voir API & intégration native pour l'authentification, les erreurs, les limites et la sécurité.

Runs — parler à un agent

POST /chat

Démarre un run durable et répond immédiatement.

Champ	Type	Défaut	Description
message	string	—	Requis. Ce que vous demandez à l'agent
app_name	string	"main"	Agent cible. N'importe quelle clé du catalogue (interactive, data_copilot, contract_review_dz, slide_master, finance_master…) ou custom_<id> pour l'un des vôtres
session_id	uuid	nouveau	Poursuivre un fil existant. Omettre pour en ouvrir un
attachments	string[]	—	Identifiants renvoyés par POST /uploads
kb_ids	string[]	—	Bases de connaissances que l'agent peut interroger pendant le run
kb_enhance	bool	false	Réécriture LLM des réponses RAG (plus lent, plus riche)
plan	bool	false	Mode plan : l'agent écrit un plan d'étapes et l'exécute, en émettant plan / plan_step
model	string	défaut du compte	Clé du catalogue de modèles — voir GET /models
reasoning	bool	false	Délibération plus longue avant de répondre
data_workspace_id	uuid	—	Espace Data Lab sur lequel travailler
client_tz	string	UTC	Fuseau IANA, ex. "Africa/Algiers"
idempotency_key	string	—	Rejouable sans risque : la même clé renvoie le même run

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

status vaut running, ou queued si la session est occupée (le run démarre automatiquement quand le précédent se termine), ou blocked.

Méthode	Chemin	Rôle
POST	/tasks	Comme /chat mais explicitement détaché — pour les traitements de fond
GET	/runs/{run_id}/events	Flux SSE du run (ci-dessous)
POST	/runs/{run_id}/respond	Répondre à une question de l'agent (user_choice, quiz, approbation)
POST	/runs/{run_id}/cancel	Arrêter un run en cours
GET	/sessions/{id}/queue	Inspecter la file d'attente de la session
POST	/sessions/{id}/queue/resume	Relancer une file mise en pause par un échec

GET /runs/{run_id}/events — le flux

text/event-stream. Chaque événement porte id (un seq monotone), event (son type) et data (JSON). Reprenable : reconnectez-vous avec Last-Event-ID: <seq> ou ?after=<seq> et tout ce qui suit ce curseur est rejoué depuis le stockage durable — rien n'est perdu, rien n'est facturé deux fois.

Groupe	Événements
Réponse	token (fragment de texte) · usage (compteurs) · done · error
Outils	tool_call · tool_result · sandbox_stdout
Plan	plan (étapes ordonnées) · plan_step (index + statut)
Documents	document_start · document_delta · document_end (porte artifact_id)
Livrables	artifact · file (PDF/DOCX/PPTX/XLSX) · image · slides · webpage · chart · sheet
Recherche	sources (résultats web) · graph (graphe de connaissances) · browser (captures computer-use) · maps
Humain dans la boucle	user_choice · choice_answer · quiz · approval (action en attente de confirmation)
Communication	email_draft · email_sent · social · call
Studios juridiques	dossier · timeline · doc_summary · findings · contract · clause · contract_compare · consultation · legal_issues · ref_check · deadline · watch_synthesis · watch_change · watch_diff
Recrutement	candidate · iv_job · iv_candidate · iv_questions · iv_grid · iv_answers · iv_ask · iv_plan
Métier	prospect · cerfa · exhibition · finance · site_map · site_pack

Consommez token, done et error pour une réponse texte simple ; le reste correspond à des cartes structurées que vous pouvez afficher ou ignorer. Les types inconnus doivent être ignorés, pas traités comme des erreurs — de nouveaux types apparaissent avec le temps.

Méthode	Chemin	Rôle
GET	/models	Catalogue de modèles disponible pour votre compte
GET	/sessions	Lister les conversations
GET	/sessions/{id}	Une session et ses derniers événements
PATCH DELETE	/sessions/{id}	Renommer / supprimer
GET	/sessions/{id}/messages	Historique complet
GET	/sessions/{id}/artifacts	Tout ce que la session a produit
POST	/sessions/{id}/branch	Bifurquer la conversation à un point donné
POST	/sessions/{id}/truncate	Tronquer la conversation à un message
GET POST	/sessions/{id}/versions	Historique / restauration des versions d'artefact
GET	/sessions/search?q=	Recherche plein texte dans vos conversations

Fichiers

Méthode	Chemin	Rôle
POST	/uploads	{filename, content_base64, mime, session_id?} → {upload_id}. Analysé automatiquement (OCR, vision, transcription). Jusqu'à 200 Mo par fichier
GET	/uploads/{id}	Statut d'analyse et texte extrait
GET	/uploads/{id}/raw	Les octets d'origine
POST	/artifacts	Créer un artefact depuis votre propre contenu
GET	/artifacts/{id}	Télécharger un fichier produit
POST	/export	Rendre du Markdown/HTML en PDF, DOCX ou PPTX
POST	/export-text	Export texte brut

Rattachez un upload à un run en passant son identifiant dans attachments. Formats acceptés : PDF, Office, images, audio, vidéo, CSV/Excel, ZIP (décompressé récursivement).

Bases de connaissances (RAG)

Méthode	Chemin	Rôle
POST GET	/kb	Créer / lister les bases
PATCH DELETE	/kb/{id}	Renommer / supprimer
GET POST	/kb/{id}/documents	Lister / ajouter des documents (ingestion asynchrone)
POST	/kb/query/stream	Interroger, en flux (ci-dessous)
GET PUT	/kb/{id}/config	Profil de recherche (juridique / entreprise / chronologie / générique), langue FTS, budgets. PUT réécrit tous les champs — envoyez l'objet complet
GET	/kb/{id}/chunks · /entities · /graph	Inspecter l'index, les entités extraites, le graphe
GET	/kb/{id}/file/{doc_id} · /image/{image_id}	Document source / image extraite
POST GET	/kb/{id}/conversations	Fils RAG multi-tours
GET	/kb/{id}/conversations/{cid}/messages	Historique du fil
GET POST DELETE	/kb/{id}/connectors …	Synchronisation depuis des sources externes ; /kb/connectors/catalog les liste
POST GET DELETE	/kb/{id}/share	Publier un lien d'interrogation public
GET	/kb/pricing	Modèle de coût par requête

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": "Quelles clauses de résiliation après 12 mois ?",
    "mode": "full", "cite": true, "enhance": false, "agent": false, "top_k": 20
  }'

Champ	Valeurs	Description
mode	auto · quick · full · deep · graph_local · graph_global	Profondeur de recherche. auto choisit selon la question
cite	bool	Citations [N] en ligne et identifiants de sources
enhance	bool	Réécriture LLM de la réponse
agent	bool	Décomposer les questions à plusieurs volets avant de chercher
doc_id	string	Restreindre la recherche à un seul document
conversation_id	uuid	Poursuivre un fil multi-tours

Agents personnalisés

Méthode	Chemin	Rôle
GET	/agent-tools	Catalogue des capacités activables sur un agent
GET POST	/agents/custom	Lister / créer
GET PUT DELETE	/agents/custom/{id}	Lire / modifier / supprimer
POST	/agents/custom/persona	Distiller un persona à partir d'écrits importés
GET	/marketplace · /marketplace/{id}	Agents publiés
POST	/marketplace/{id}/install · /publish · /unpublish	Installer / publier / retirer

{
  "name": "Analyste appels d'offres", "emoji": "📑",
  "description": "Lit les dossiers d'appel d'offres et produit une note go / no-go",
  "instruction": "Tu es analyste en marchés publics…",
  "tool_keys": ["web", "deep_research", "documents", "knowledge_base", "database"],
  "model": "standard", "visibility": "private",
  "examples": ["Analyse cet appel d'offres"], "tags": ["achats"]
}

Clés de capacités : 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.

Lancez-le comme n'importe quel agent : POST /chat avec "app_name": "custom_<id>".

Planificateur

Méthode	Chemin	Rôle
GET POST	/cron	Lister / créer une exécution planifiée
PATCH DELETE	/cron/{id}	Suspendre, modifier, supprimer
POST	/cron/{id}/run	Déclencher une fois, maintenant

{ "name": "Veille concurrence du lundi", "cron_expr": "0 8 * * 1",
  "timezone": "Africa/Algiers", "prompt": "Résume les mouvements de la semaine…",
  "app_name": "main", "delivery_email": "equipe@acme.com" }

Cron standard à 5 champs. delivery_email envoie la réponse finale par e-mail ; laissez vide pour désactiver.

Data Lab

Méthode	Chemin	Rôle
GET POST	/data/workspaces	Lister / créer un espace DuckDB persistant
PATCH DELETE	/data/workspaces/{id}	Renommer / supprimer
POST	/data/workspaces/{id}/ingest	Charger de l'Excel/CSV — feuilles désordonnées, en-têtes multi-lignes, plusieurs tables par feuille
GET	/data/workspaces/{id}/tables · /files	Inspecter le schéma et les sources
POST	/data/workspaces/{id}/query	Exécuter du SQL sur l'espace
DELETE	/data/workspaces/{id}/tables/{table}	Supprimer une table

Essaim d'agents

Méthode	Chemin	Rôle
GET	/swarm/api/teams · /catalogue · /health	Équipes disponibles et état du moteur
POST	/swarm/api/run	Démarrer un run multi-agents
GET	/swarm/api/run/{id}/stream	Progression en SSE
POST	/swarm/api/run/{id}/cancel	L'arrêter
GET	/swarm/api/dossiers · /{id} · /{id}/file/{name}	Dossiers produits et leurs fichiers
POST	/swarm/api/convert · /template/inspect	Convertir la sortie / inspecter un modèle de deck

Documents & projets

Méthode	Chemin	Rôle
GET	/docspace	Arborescence de dossiers et documents
POST PATCH DELETE	/folders, /folders/{id}	Gérer les dossiers
POST PATCH DELETE	/documents, /documents/{id}	Gérer les documents
GET	/documents/{id}/content	Lire le contenu
POST	/documents/{id}/attach	Rattacher un document à une conversation
POST	/docspace/import-zip	Import en masse
GET POST	/projects, /projects/{id}	Espaces regroupant conversations et fichiers
POST GET DELETE	/projects/{id}/members	Accès au projet

Partage (liens publics)

Méthode	Chemin	Rôle
POST GET DELETE	/sessions/{id}/share	Publier une conversation
GET	/shared/{slug}	Public — lecture d'une conversation partagée
GET	/shared/{slug}/artifacts/{id}	Public — artefact d'une conversation partagée
GET POST	/shared/{slug}/comments	Public — fil de commentaires
POST	/shared/{slug}/clone	Copier une conversation partagée dans votre compte
POST GET DELETE	/docshare	Partager documents et dossiers
GET	/shared-doc/{slug}	Public — document partagé
GET	/shared-kb/{slug} · POST /shared-kb/{slug}/query/stream	Public — lien de base de connaissances, requêtes facturées au propriétaire

Un lien public est une URL non listée, pas une authentification. Ce que vous publiez est lisible par quiconque détient le lien — et les requêtes sur une base partagée vous sont facturées à vous. Révoquez avec le DELETE correspondant.

Widget embarquable

Créez un widget dans Intégrations → Widget, puis collez une ligne dans votre site :

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

data-position="bottom-left" | "bottom-right" en option. Le widget appelle une API publique distincte sous /embed-api — la clé publique n'est pas une clé API et ne peut pas lire votre compte :

Méthode	Chemin	Rôle
GET	/embed-api/config/{public_key}	Public — configuration du widget
POST	/embed-api/chat	Public — message d'un visiteur
GET	/embed-api/runs/{run_id}/events	Public — flux de la réponse
GET	/embed-api/history/{public_key}/{visitor_id}	Public — historique du visiteur
GET POST PATCH DELETE	/embed-widgets	CRUD propriétaire (authentifié)

Les chemins /embed-api/* et /scim/v2/* sont servis à la racine du domaine, pas sous /api/v1 — ex. https://ai.syctra.com/embed-api/chat.

Seuls les agents autorisés en usage public peuvent être rattachés à un widget, le trafic visiteur est limité par widget, et chaque conversation est facturée à l'organisation propriétaire. Restreignez les origines autorisées avant de publier.

Équipes, organisation & provisioning

Méthode	Chemin	Rôle
GET	/enterprise · /enterprise/analytics · /enterprise/retention	Organisation, usage, politique de rétention
POST DELETE	/enterprise/teams, /teams/{id}	Gérer les équipes
POST DELETE	/enterprise/teams/{id}/members…	Composition
POST DELETE	/enterprise/teams/{id}/grants	Quels agents une équipe peut utiliser
POST	/enterprise/teams/{id}/invite · /invites/revoke · /invites/resend	Invitations
GET POST	/invite/{token}, /invite/{token}/accept	Public — acceptation d'invitation
GET PUT DELETE	/enterprise/sso	Authentification unique SAML / OIDC
POST	/enterprise/scim-token	Émettre un jeton de provisioning SCIM
GET	/me/caps · /me/teams · POST /me/active-team	Droits et équipes de l'appelant
GET POST DELETE	/teams, /groups, /share-targets	Équipes légères, groupes, cibles de partage

SCIM 2.0 est servi sur https://ai.syctra.com/scim/v2 avec son propre jeton (ce n'est pas une clé API) : GET|POST /Users, GET|PUT|PATCH|DELETE /Users/{id}, GET /Groups.

Compte, notifications & confidentialité

Méthode	Chemin	Rôle
GET PATCH	/auth/me	Profil
POST	/auth/change-password · /auth/logout	Identifiants / déconnexion
GET	/balance	Solde de crédits
GET POST	/notifications, /notifications/read	Fil de notifications
PUT	/me/notify-email · /me/low-balance-pct	Préférences de notification
GET POST	/push/vapid-key, /push/subscribe	Abonnements Web Push
GET DELETE PUT	/memory, /memory/{id}, /memory/settings	Mémoire long terme : lire, supprimer, désactiver
GET	/account/export	RGPD — exporter tout ce qui vous appartient
DELETE	/account	RGPD — supprimer le compte et ses données
GET POST	/approvals, /approvals/{id}/decide	Approuver ou refuser une action sous contrôle
GET PUT	/approval-settings	Quelles capacités exigent une approbation humaine

Autres surfaces

Méthode	Chemin	Rôle
GET POST DELETE	/deadlines…	Agenda des échéances juridiques
POST GET DELETE	/meetings…	Transcription de réunions et comptes rendus
POST GET DELETE	/dubbings…, GET /dubbing/languages	Travaux de doublage vidéo / audio
POST GET DELETE	/email-compose, /email-templates	E-mails composés et modèles
POST	/email/send	Envoyer un e-mail via la plateforme
GET POST DELETE	/prompts	Prompts enregistrés
POST	/feedback · /message-feedback	Retours produit et par réponse
GET	/healthz · /readyz · /metrics	Public — liveness, readiness, métriques Prometheus

Notes pour intégrateurs

• Il n'y a pas encore de webhooks sortants. Suivez les traitements longs en gardant le flux SSE ouvert, ou en interrogeant GET /sessions/{id} — le run survit à votre déconnexion.
• Interrogez sobrement. Préférez le SSE ; si vous devez interroger, utilisez le cursor que vous détenez déjà.
• Conservez le curseur. Persister le dernier seq traité rend votre intégration résistante aux plantages.
• Fixez l'agent. app_name détermine le comportement, le coût et les outils disponibles — définissez-le explicitement plutôt que de compter sur le défaut main.
• Gérez 402 et 429 en priorité. Ce sont les deux erreurs qu'une intégration saine rencontre en production ; le reste trahit généralement un payload incorrect.