Français
Assistant
Les routes sont relatives à <PUBLIC_BASE_URL> ; les corps de requête et de réponse sont en JSON sauf mention contraire. L’authentification, les portées, la pagination et le format des erreurs sont décrits dans les guides de l’API REST.
GET /api/v1/assistant/models
Lister les modèles disponibles pour l’assistant
Le modèle par défaut de l’instance et les choix offerts au membre.
Accès — Session de membre ou clé d’API portant assistant:read.
Réponses
200 — Les modèles.
| Champ | Type | Requis |
|---|---|---|
default | object | null | oui |
options | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"default": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string" },
"source": {
"type": "string",
"enum": [ "purpose", "instanceDefault", "configurationOrder" ]
}
},
"required": [ "provider", "model", "source" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string" },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"connectionLabel": { "type": "string" },
"supportsTools": { "type": "boolean" }
},
"required": [
"provider",
"model",
"connectionId",
"connectionLabel",
"supportsTools"
],
"additionalProperties": false
}
}
},
"required": [ "default", "options" ],
"additionalProperties": false
}401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
GET /api/v1/assistant/conversations
Lister mes conversations
Les conversations les plus récentes du membre, éventuellement celles rattachées à un workflow.
Accès — Session de membre ou clé d’API portant assistant:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
workflowId | requête | string | non |
limit | requête | integer | non |
Réponses
200 — Les conversations.
| Champ | Type | Requis |
|---|---|---|
conversations | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"conversations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"title": { "type": "string" },
"workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"model": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"lastModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"status": {
"type": "string",
"enum": [ "idle", "running", "failed", "cancelled" ]
},
"usage": {
"type": "object",
"properties": {
"calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"costUsd": {
"anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ]
}
},
"required": [ "calls", "inputTokens", "outputTokens", "costUsd" ],
"additionalProperties": false
},
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"title",
"workflowId",
"model",
"lastModel",
"status",
"usage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
}
},
"required": [ "conversations" ],
"additionalProperties": false
}400 — La requête ne respecte pas son schéma.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
POST /api/v1/assistant/conversations
Ouvrir une conversation
Crée une conversation vide, éventuellement rattachée à un workflow et avec un modèle choisi. Un modèle hors des choix autorisés est assistant.model_not_allowed.
Accès — Session de membre ou clé d’API portant assistant:write.
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
workflowId | string | non |
title | string | non |
model | object | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"workflowId": { "type": "string", "minLength": 1 },
"title": { "type": "string", "minLength": 1, "maxLength": 120 },
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ]
}
}
}Réponses
201 — La conversation.
| Champ | Type | Requis |
|---|---|---|
conversation | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"conversation": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"title": { "type": "string" },
"workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"model": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"lastModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"status": {
"type": "string",
"enum": [ "idle", "running", "failed", "cancelled" ]
},
"usage": {
"type": "object",
"properties": {
"calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"costUsd": {
"anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ]
}
},
"required": [ "calls", "inputTokens", "outputTokens", "costUsd" ],
"additionalProperties": false
},
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"title",
"workflowId",
"model",
"lastModel",
"status",
"usage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
},
"required": [ "conversation" ],
"additionalProperties": false
}400 — La requête ne respecte pas son schéma.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.
Codes d’erreur — assistant.bad_request, assistant.model_not_allowed, assistant.tools_not_supported. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
GET /api/v1/assistant/conversations/{id}
Lire une conversation
La conversation, ses messages et ses propositions. Tout ce qu’un tour diffusé a produit est persisté : c’est ainsi qu’une connexion coupée se rattrape. La conversation d’un autre membre est un 404.
Accès — Session de membre ou clé d’API portant assistant:read.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — La conversation.
| Champ | Type | Requis |
|---|---|---|
conversation | object | oui |
messages | object[] | oui |
proposals | object[] | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"conversation": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"title": { "type": "string" },
"workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"model": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"lastModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"status": {
"type": "string",
"enum": [ "idle", "running", "failed", "cancelled" ]
},
"usage": {
"type": "object",
"properties": {
"calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"costUsd": {
"anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ]
}
},
"required": [ "calls", "inputTokens", "outputTokens", "costUsd" ],
"additionalProperties": false
},
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"title",
"workflowId",
"model",
"lastModel",
"status",
"usage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"role": { "type": "string", "enum": [ "user", "assistant", "tool" ] },
"content": { "type": "string" },
"toolCalls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"arguments": {}
},
"required": [ "id", "name", "arguments" ],
"additionalProperties": false
}
},
"toolCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"toolName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"toolOk": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] },
"toolResult": { "anyOf": [ {}, { "type": "null" } ] },
"model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" }
},
"required": [
"id",
"role",
"content",
"toolCalls",
"toolCallId",
"toolName",
"toolOk",
"toolResult",
"model",
"createdAt"
],
"additionalProperties": false
}
},
"proposals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"conversationId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": { "type": "string", "enum": [ "create_draft", "update_draft" ] },
"status": {
"type": "string",
"enum": [
"proposed",
"accepting",
"accepted",
"rejected",
"stale",
"failed"
]
},
"summary": { "type": "string" },
"name": { "type": "string" },
"workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"baseVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"graph": {
"type": "object",
"properties": {
"id": {},
"workflowId": {},
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {},
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": {
"type": "integer",
"minimum": 1000,
"maximum": 3600000
}
},
"required": [ "maxAttempts" ],
"additionalProperties": false
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name", "params", "onError" ],
"additionalProperties": false
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {},
"output": { "type": "string" },
"to": {},
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ],
"additionalProperties": false
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ],
"additionalProperties": false
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "text", "position", "size", "color" ],
"additionalProperties": false
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ],
"additionalProperties": false
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "code", "message", "nodeId" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "code", "message", "nodeId" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
},
"diff": {
"anyOf": [
{
"type": "object",
"properties": {
"addedNodes": { "type": "array", "items": { "type": "string" } },
"removedNodes": { "type": "array", "items": { "type": "string" } },
"changedNodes": { "type": "array", "items": { "type": "string" } },
"addedConnections": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"removedConnections": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"renamed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [
"addedNodes",
"removedNodes",
"changedNodes",
"addedConnections",
"removedConnections",
"renamed"
],
"additionalProperties": false
},
{ "type": "null" }
]
},
"tables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": { "type": "string", "minLength": 1, "maxLength": 60 },
"name": { "type": "string", "minLength": 1, "maxLength": 120 },
"columns": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Machine key: lowercase, a-z0-9_."
},
"label": { "type": "string", "minLength": 1, "maxLength": 120 },
"type": {
"type": "string",
"enum": [
"text",
"number",
"boolean",
"date",
"datetime",
"select",
"email"
]
},
"isKey": {
"type": "boolean",
"description": "Part of the row key used to find/update a row."
}
},
"required": [ "key", "label", "type", "isKey" ],
"additionalProperties": false
}
}
},
"required": [ "slug", "name", "columns" ],
"additionalProperties": false
}
},
"prerequisites": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "table" },
"ref": { "type": "string" },
"slug": { "type": "string" },
"name": { "type": "string" },
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Machine key: lowercase, a-z0-9_."
},
"label": { "type": "string", "minLength": 1, "maxLength": 120 },
"type": {
"type": "string",
"enum": [
"text",
"number",
"boolean",
"date",
"datetime",
"select",
"email"
]
},
"isKey": {
"type": "boolean",
"description": "Part of the row key used to find/update a row."
}
},
"required": [ "key", "label", "type", "isKey" ],
"additionalProperties": false
}
}
},
"required": [ "kind", "ref", "slug", "name", "columns" ],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "connection" },
"connection": { "type": "string" },
"credentialType": { "type": "string" },
"capability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"nodeId": { "type": "string" },
"nodeType": { "type": "string" }
},
"required": [
"kind",
"connection",
"credentialType",
"capability",
"nodeId",
"nodeType"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "complete" },
"nodeId": { "type": "string" },
"nodeType": { "type": "string" },
"param": { "type": "string" },
"label": {
"type": "object",
"properties": { "fr": { "type": "string" }, "en": { "type": "string" } },
"required": [ "fr", "en" ],
"additionalProperties": false
}
},
"required": [ "kind", "nodeId", "nodeType", "param", "label" ],
"additionalProperties": false
}
]
}
},
"result": {
"anyOf": [
{
"type": "object",
"properties": {
"workflowId": { "type": "string" },
"versionId": { "type": "string" },
"createdTables": { "type": "array", "items": { "type": "string" } }
},
"required": [ "workflowId", "versionId", "createdTables" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"decidedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [
"id",
"conversationId",
"kind",
"status",
"summary",
"name",
"workflowId",
"baseVersionId",
"graph",
"validation",
"diff",
"tables",
"prerequisites",
"result",
"failureCode",
"createdAt",
"decidedAt"
],
"additionalProperties": false
}
}
},
"required": [ "conversation", "messages", "proposals" ],
"additionalProperties": false
}401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.conversation_not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
PATCH /api/v1/assistant/conversations/{id}
Renommer une conversation ou changer son modèle
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
title | string | non |
model | object | null | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"title": { "type": "string", "minLength": 1, "maxLength": 120 },
"model": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ]
},
{ "type": "null" }
]
}
}
}Réponses
200 — La conversation, mise à jour.
| Champ | Type | Requis |
|---|---|---|
conversation | object | oui |
Même schéma que POST /api/v1/assistant/conversations.
400 — La requête ne respecte pas son schéma.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.bad_request, assistant.conversation_not_found, assistant.model_not_allowed, assistant.tools_not_supported. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
DELETE /api/v1/assistant/conversations/{id}
Supprimer une conversation
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
204 — Supprimée.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.conversation_not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
POST /api/v1/assistant/conversations/{id}/messages
Envoyer un message et jouer un tour
Un tour de l’assistant : il lit le message, peut appeler des outils, et peut laisser une proposition à accepter ou refuser. Deux réponses pour une requête. Avec Accept: text/event-stream, un 200 part aussitôt et le tour arrive en server-sent events (event: est le type, data: l’événement JSON), terminé par assistant.turn_done portant le tour complet, ou assistant.error portant le code d’erreur : les refus comme 409 assistant.busy arrivent DANS le flux. Sinon le JSON du tour complet est rendu, ou l’erreur avec son statut. Fermer la connexion n’arrête pas le tour : cancel existe pour ça.
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Corps de la requête (application/json)
| Champ | Type | Requis |
|---|---|---|
content | string | oui |
model | object | null | non |
Schéma JSON
json
{
"type": "object",
"properties": {
"content": { "type": "string", "minLength": 1, "maxLength": 12000 },
"model": {
"anyOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai",
"mistral",
"openrouter",
"ollama",
"openai_compatible"
]
},
"model": { "type": "string", "minLength": 1, "maxLength": 200 },
"connectionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [ "provider", "model" ]
},
{ "type": "null" }
]
}
},
"required": [ "content" ]
}Réponses
200 — Le flux d’événements (text/event-stream). Sans l’en-tête Accept, le corps est à la place le JSON du tour complet (AssistantTurnResponse, le même objet que porte assistant.turn_done).
Type de contenu : text/event-stream
400 — La requête ne respecte pas son schéma.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.
Codes d’erreur — assistant.bad_request, assistant.conversation_not_found, assistant.busy, assistant.model_not_allowed, assistant.tools_not_supported, assistant.budget_exceeded, assistant.cancelled. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
POST /api/v1/assistant/conversations/{id}/cancel
Interrompre le tour en cours
cancelled: false quand aucun tour ne tournait. Le tour diffusé se termine alors par assistant.error avec le code assistant.cancelled.
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — Si un tour a été interrompu.
| Champ | Type | Requis |
|---|---|---|
cancelled | boolean | oui |
Schéma JSON
json
{
"type": "object",
"properties": { "cancelled": { "type": "boolean" } },
"required": [ "cancelled" ],
"additionalProperties": false
}401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.conversation_not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
POST /api/v1/assistant/proposals/{id}/accept
Accepter une proposition
Applique la proposition : crée le brouillon, ou met à jour celui rattaché. 409 assistant.proposal_decided si déjà acceptée ou refusée ; 409 assistant.proposal_stale si le brouillon a changé depuis la proposition.
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — La proposition, acceptée.
| Champ | Type | Requis |
|---|---|---|
proposal | object | oui |
Schéma JSON
json
{
"type": "object",
"properties": {
"proposal": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"conversationId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": { "type": "string", "enum": [ "create_draft", "update_draft" ] },
"status": {
"type": "string",
"enum": [ "proposed", "accepting", "accepted", "rejected", "stale", "failed" ]
},
"summary": { "type": "string" },
"name": { "type": "string" },
"workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"baseVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"graph": {
"type": "object",
"properties": {
"id": {},
"workflowId": {},
"nodes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {},
"type": { "type": "string", "minLength": 1, "maxLength": 128 },
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"params": {
"default": {},
"type": "object",
"propertyNames": { "type": "string" },
"additionalProperties": {}
},
"onError": {
"default": "fail",
"type": "string",
"enum": [ "fail", "continue", "errorPort" ]
},
"retry": {
"type": "object",
"properties": {
"maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
"delayMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
},
"required": [ "maxAttempts" ],
"additionalProperties": false
},
"timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 1800000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"disabled": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 2000 }
},
"required": [ "id", "type", "version", "name", "params", "onError" ],
"additionalProperties": false
}
},
"connections": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {},
"output": { "type": "string" },
"to": {},
"input": { "type": "string" },
"kind": { "type": "string", "enum": [ "data", "service" ] }
},
"required": [ "from", "output", "to" ],
"additionalProperties": false
}
},
"notes": {
"readOnly": true,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 64 },
"text": { "default": "", "type": "string", "maxLength": 4000 },
"position": {
"type": "object",
"properties": { "x": { "type": "number" }, "y": { "type": "number" } },
"required": [ "x", "y" ],
"additionalProperties": false
},
"size": {
"default": { "width": 240, "height": 160 },
"type": "object",
"properties": {
"width": { "type": "number", "minimum": 120, "maximum": 2000 },
"height": { "type": "number", "minimum": 80, "maximum": 2000 }
},
"required": [ "width", "height" ],
"additionalProperties": false
},
"color": {
"default": "jaune",
"type": "string",
"enum": [ "jaune", "menthe", "ciel", "rose", "lavande" ]
}
},
"required": [ "id", "text", "position", "size", "color" ],
"additionalProperties": false
}
},
"pins": {
"type": "object",
"propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
"additionalProperties": {
"type": "object",
"properties": {
"output": {},
"port": { "type": "string" },
"pinnedAt": { "type": "string", "minLength": 1, "maxLength": 64 }
},
"required": [ "output", "pinnedAt" ],
"additionalProperties": false
}
}
},
"required": [ "id", "workflowId", "nodes", "connections" ],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"ok": { "type": "boolean" },
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "code", "message", "nodeId" ],
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [ "code", "message", "nodeId" ],
"additionalProperties": false
}
}
},
"required": [ "ok", "errors", "warnings" ],
"additionalProperties": false
},
"diff": {
"anyOf": [
{
"type": "object",
"properties": {
"addedNodes": { "type": "array", "items": { "type": "string" } },
"removedNodes": { "type": "array", "items": { "type": "string" } },
"changedNodes": { "type": "array", "items": { "type": "string" } },
"addedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"removedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"renamed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [
"addedNodes",
"removedNodes",
"changedNodes",
"addedConnections",
"removedConnections",
"renamed"
],
"additionalProperties": false
},
{ "type": "null" }
]
},
"tables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": { "type": "string", "minLength": 1, "maxLength": 60 },
"name": { "type": "string", "minLength": 1, "maxLength": 120 },
"columns": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Machine key: lowercase, a-z0-9_."
},
"label": { "type": "string", "minLength": 1, "maxLength": 120 },
"type": {
"type": "string",
"enum": [
"text",
"number",
"boolean",
"date",
"datetime",
"select",
"email"
]
},
"isKey": {
"type": "boolean",
"description": "Part of the row key used to find/update a row."
}
},
"required": [ "key", "label", "type", "isKey" ],
"additionalProperties": false
}
}
},
"required": [ "slug", "name", "columns" ],
"additionalProperties": false
}
},
"prerequisites": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "table" },
"ref": { "type": "string" },
"slug": { "type": "string" },
"name": { "type": "string" },
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Machine key: lowercase, a-z0-9_."
},
"label": { "type": "string", "minLength": 1, "maxLength": 120 },
"type": {
"type": "string",
"enum": [
"text",
"number",
"boolean",
"date",
"datetime",
"select",
"email"
]
},
"isKey": {
"type": "boolean",
"description": "Part of the row key used to find/update a row."
}
},
"required": [ "key", "label", "type", "isKey" ],
"additionalProperties": false
}
}
},
"required": [ "kind", "ref", "slug", "name", "columns" ],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "connection" },
"connection": { "type": "string" },
"credentialType": { "type": "string" },
"capability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"nodeId": { "type": "string" },
"nodeType": { "type": "string" }
},
"required": [
"kind",
"connection",
"credentialType",
"capability",
"nodeId",
"nodeType"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": { "type": "string", "const": "complete" },
"nodeId": { "type": "string" },
"nodeType": { "type": "string" },
"param": { "type": "string" },
"label": {
"type": "object",
"properties": { "fr": { "type": "string" }, "en": { "type": "string" } },
"required": [ "fr", "en" ],
"additionalProperties": false
}
},
"required": [ "kind", "nodeId", "nodeType", "param", "label" ],
"additionalProperties": false
}
]
}
},
"result": {
"anyOf": [
{
"type": "object",
"properties": {
"workflowId": { "type": "string" },
"versionId": { "type": "string" },
"createdTables": { "type": "array", "items": { "type": "string" } }
},
"required": [ "workflowId", "versionId", "createdTables" ],
"additionalProperties": false
},
{ "type": "null" }
]
},
"failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
"createdAt": { "type": "string" },
"decidedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
},
"required": [
"id",
"conversationId",
"kind",
"status",
"summary",
"name",
"workflowId",
"baseVersionId",
"graph",
"validation",
"diff",
"tables",
"prerequisites",
"result",
"failureCode",
"createdAt",
"decidedAt"
],
"additionalProperties": false
}
},
"required": [ "proposal" ],
"additionalProperties": false
}401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.proposal_not_found, assistant.proposal_decided, assistant.proposal_stale. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.
POST /api/v1/assistant/proposals/{id}/reject
Refuser une proposition
Rien n’est appliqué. 409 assistant.proposal_decided si déjà acceptée ou refusée.
Accès — Session de membre ou clé d’API portant assistant:write.
Paramètres
| Nom | Où | Type | Requis |
|---|---|---|---|
id | chemin | string | oui |
Réponses
200 — La proposition, refusée.
| Champ | Type | Requis |
|---|---|---|
proposal | object | oui |
Même schéma que POST /api/v1/assistant/proposals/{id}/accept.
401 — Aucune session ni clé d’API valide (auth.unauthenticated).
403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).
429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.
Codes d’erreur — assistant.proposal_not_found, assistant.proposal_decided. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.