API HTTP · Documentation Subagent

Chaque outil du MCP s’appelle aussi en HTTP : POST https://api.subagent.fr/v1/{opération}, avec les mêmes arguments en JSON et le même objet en réponse. Sous /v1, chaque route est un outil.

En bref

Propriété	Valeur
Adresse	`https://api.subagent.fr/v1/{opération}`, où `{opération}` est le nom d’un outil : `send_email`, `list_threads`…
Méthode	`POST`, pour toutes les opérations, lectures comprises
Corps	Un objet JSON : les arguments de l’outil. Un corps vide vaut `{}`. 1 Mio au plus.
Authentification	En-tête `Authorization: Bearer sak_…`. Seul `sign_up` s’appelle sans clé.
Réponse	Statut 200 et l’objet structuré de l’outil
Refus	Un statut HTTP et `{"error": {"code", "message", "hint"}}`
Schémas	`https://api.subagent.fr/openapi.json` (OpenAPI 3.1), lisible sans clé

Un appel

Terminal

curl -X POST https://api.subagent.fr/v1/inbox_status \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

La réponse est l’objet que l’outil rend par MCP dans structuredContent. Le texte lisible, lui, n’existe que par MCP.

S’inscrire et vérifier en HTTP

Terminal

curl -X POST https://api.subagent.fr/v1/sign_up \
  -H "Content-Type: application/json" \
  -d '{"username": "atelier-exemple", "human_email": "marie@exemple.fr"}'

La réponse porte api_key : la clé, affichée une seule fois. Les appels suivants la présentent.

Terminal

curl -X POST https://api.subagent.fr/v1/verify \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp_code": "482913"}'

Les refus

JSON

{
  "error": {
    "code": "space_unverified",
    "message": "…",
    "hint": "…"
  }
}

code : stable. C’est lui qu’un programme teste.
message : une phrase en français.
hint : la piste, quand il y en a une. Elle dit quoi faire.

Statut	Sens
400	Un argument manque, est inconnu ou mal formé : `invalid_argument`.
401	La clé est absente, inconnue ou révoquée : `unauthorized`.
402	L’espace n’a pas de forfait en cours : `payment_required`.
403	La clé ne porte pas la permission (`forbidden`), l’espace n’est pas vérifié (`space_unverified`), ou l’appel vient d’une page web (`origin_refused`).
404	L’objet ou l’opération n’existe pas : `not_found`, `unknown_operation`.
409	L’état ne permet pas l’action : `duplicate_recipient`, `not_draft`, `inbox_suspended`…
413	Le corps dépasse 1 Mio : `payload_too_large`.
422	La demande est comprise mais refusée : `recipient_suppressed`, `own_domain_required`, `unresolved_placeholder`…
429	Une limite est atteinte : `rate_limited`, `key_daily_cap`, `queue_full`…
500, 502, 503	Le service, ou un service dont il dépend, n’a pas répondu : `internal`, `provisioning_failed`, `dns_unavailable`, `billing_unavailable`…

Chaque code, avec ce qu’il faut faire : Erreurs.

Un message retenu n’est pas un refus. Quota du jour atteint, envoi hors des heures ouvrées, volume du mois atteint : la réponse est un succès (200), et le message est en file (queued). estimated_send_at donne son départ au plus tôt, d’après le créneau et le quota du jour.

Parcourir une liste

Les listes rendent items et next_cursor.

limit va de 1 à 100. 20 par défaut.
Tant que next_cursor n’est pas null, repassez-le tel quel dans cursor pour la page suivante.
Un curseur ne se fabrique pas : un curseur illisible est refusé avec le code invalid_argument.

Terminal

curl -X POST https://api.subagent.fr/v1/list_threads \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unanswered": true, "limit": 50}'

get_thread suit la même règle pour les messages d’un fil : 50 par appel, puis next_cursor. list_domains rend tous les domaines de l’espace en une fois.

Réessayer sans doublon

send_email et reply_to_thread acceptent une idempotency_key, de 1 à 255 caractères. En HTTP, l’en-tête Idempotency-Key vaut le paramètre.

Même clé, même contenu : le serveur rend le message déjà créé, avec replayed = true.
Même clé, contenu différent : refus idempotency_conflict. Rien n’est envoyé.

Après une erreur 500 ou une coupure réseau, réessayez avec la même idempotency_key.

Les formes

Identifiants : inb_… (boîte), thr_… (fil), msg_… (message), dom_… (domaine), suivis de 32 caractères hexadécimaux. Passez-les tels que les outils les rendent.
Dates : ISO 8601 avec fuseau, à l’heure de Paris : 2026-10-13T09:00:00+02:00. En entrée, une heure de Paris sans fuseau est acceptée : 2026-10-13T09:00.
Arguments : un argument inconnu est refusé, avec la liste des arguments acceptés dans la piste.

Débit

60 requêtes par minute sans clé, 600 avec une clé, par adresse du client. Au-delà : statut 429, code rate_limited, et l’en-tête Retry-After donne le nombre de secondes à attendre. Voir Limites et quotas.

Depuis un navigateur

L’API ne s’appelle pas depuis la page web d’un autre site : une requête qui porte un en-tête Origin étranger est refusée avec le code origin_refused. Appelez-la depuis votre agent ou votre serveur.

La référence du serveur

https://api.subagent.fr/openapi.json : chaque opération, ses schémas d’entrée et de sortie, ses permissions (x-subagent-permissions).
https://api.subagent.fr/llms.txt : les règles et la liste des outils, en texte.
Les pages du service qui ne sont pas des outils : la connexion d’un assistant (/oauth/…, voir Connecteur), la page de paiement et les factures (voir Prix et paiement), la page de désinscription.
Référence des outils : une page par outil, produite depuis ce registre.