Référence API
Décisions HTTP, auth, contrats de réponse et exemples TypeScript pour Choice, Score et yes-no.
System One fournit des choix structurés, des scores et des probabilités oui/non via HTTP. Cette référence couvre l’API de décision hébergée et les points de terminaison de compte de la console. Le SDK System One est aussi un chemin d’intégration de premier ordre, avec ses propres adaptateurs et ses propres identifiants.
Prêt pour les questions
Qu’est-ce que l’API System One ? L’API de décision hébergée pour Choice, Score et Noul (oui/non). Authentifiez-vous avec une clé d’API et recevez des décisions typées pour vos agents.
Les erreurs, l’idempotence et le versioning ? Consultez les pages filles sous /fr/docs/api/.
URL de base et authentification
| Paramètre | Valeur |
|---|---|
| URL de base | https://system-one.dev/v1 |
| Endpoint de décision et d’extraction | POST https://system-one.dev/v1/systemone |
| Authentification | Authorization: Bearer YOUR_API_KEY |
| Format de requête | Content-Type: application/json |
| Modèle | Copiez l’identifiant exact (name) de la liste des modèles. |
Créez une clé d’API dans votre console System One et conservez-la dans un gestionnaire de secrets ou sur votre serveur, jamais dans du code navigateur, des documents partagés ou des captures d’écran. Les requêtes utilisent les crédits de votre compte.
L’origine de l’API est l’application principale, pas l’hôte de documentation. POST /v1/systemone exige une clé Bearer System One et accepte des questions de décision ou des fields d’extraction ; GET /v1/models est public. Les endpoints de compte /api/system-one/* utilisent votre session de navigateur connectée.
POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/jsonGET /v1/models
Récupérez la liste courante des modèles. Cet endpoint est public et ne consomme pas de crédits de décision.
curl 'https://system-one.dev/v1/models' \
-H 'Accept: application/json'La réponse JSON est un objet contenant un tableau models. Ne supposez ni un nombre ni un ordre fixe d’entrées.
| Champ du modèle | Utilisation |
|---|---|
name | Valeur exacte à copier dans le champ model de la requête. |
displayName | Nom lisible pour la sélection. |
description | Description du modèle. |
pricing.creditsPerBlock | Crédits par question et par bloc de facturation. |
pricing.bytesPerBlock | Nombre d’octets de requête dans un bloc de facturation. |
capabilities.inputs, capabilities.questions | Types d’entrées et de questions pris en charge. |
limits | Limites de requête, dont bytes pour le corps complet et, le cas échéant, images: { count, bytesPerImage, totalBytes }. |
La liste des modèles peut changer ; gardez la sélection ouverte aux nouvelles entrées plutôt que d’encoder un catalogue permanent.
POST /v1/systemone
Enregistrez ce corps sous request.json :
{
"model": "YOUR_MODEL_ID",
"state": { "message": "I was charged twice for one order." },
"questions": {
"team": {
"type": "choice",
"instructions": "Choose the reviewing team.",
"criteria": { "billing": "Payments and refunds", "support": "Technical help" }
},
"urgency": {
"type": "score",
"instructions": "Evaluate urgency with the ordered rubric.",
"criteria": ["Normal review", "Timely response", "Immediate human attention"]
},
"duplicate": {
"type": "noul",
"instructions": "Does the message report a duplicate charge?"
}
}
}Envoyez-le avec votre clé et une clé d’opération unique :
curl --include 'https://system-one.dev/v1/systemone' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_OPERATION_KEY' \
--data-binary @request.jsonChamps de requête
| Champ | Ce qu’il faut envoyer |
|---|---|
model | Le name de l’entrée sélectionnée, une chaîne non vide d’au plus 128 caractères. Envoyez-le explicitement. |
state | Contexte partagé requis : une chaîne, un objet JSON ou un tableau. "" est autorisé. |
images | Tableau ordonné facultatif d’ImageInput : data URLs base64 intégrées ou objets mediaType + base64. |
questions | Objet contenant 1 à 32 questions nommées. |
questions.*.type | choice, score ou noul. Le type HTTP d’une probabilité oui/non est noul, pas boolean. |
questions.*.instructions | Chaîne non vide expliquant la question. |
criteria de Choice | Objet associant les noms d’options à des descriptions. Maximum : 255. |
criteria de Score | Tableau de 2 à 10 descriptions ordonnées, à partir de l’index 0. |
criteria de Noul | Objet facultatif avec des descriptions true et/ou false. |
Limites
| Limite | Plafond |
|---|---|
| Corps de requête JSON UTF-8 | 64 KB pour les modèles texte ; 13 Mo pour les modèles compatibles avec les images |
| Images sur les modèles pris en charge | Jusqu’à 4 ; 4 Mo décodés chacune ; 8 Mo décodés au total |
| Questions par requête | 32 |
| Options de Choice | 255 |
| Niveaux de Score | 2 à 10 |
En-têtes de réponse
Les crédits, l’identifiant de requête et l’état de rejeu se lisent dans les en-têtes documentés : X-Request-Id, X-System-One-Credits, X-Idempotency-Replayed et X-RateLimit-*. Le corps de la réponse contient les réponses typées, par exemple :
{
"model": "jev",
"answers": {
"team": { "type": "choice", "choice": "support", "probabilities": { "billing": 0.2, "support": 0.8 }, "confidence": 0.6 },
"duplicate": { "type": "noul", "noul": 0.83 }
}
}usage.input_tokens et usage.output_tokens peuvent être null ou absents : c’est alors une valeur inconnue, jamais zéro.
Extraction
La même route accepte une requête d’extraction avec fields au lieu de questions :
{
"model": "clairic",
"state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02.",
"fields": {
"invoice_number": { "type": "text", "instructions": "The invoice id" },
"total": { "type": "number", "decimals": 2 }
}
}Voir Extraire des champs avec Clairic pour les types de champs et les images.
Exemple TypeScript
const result = await client.evaluate(request, {
headers: { 'Idempotency-Key': operation.idempotencyKey },
});
console.log(result.answers.team.choice);