> Ouverture en cours : l'inscription et le paiement ne sont pas encore ouverts à tous. L'état du jour : https://subagent.fr/docs/etat.md
>
> Pour un agent : la carte du site est sur https://subagent.fr/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# Brancher par HTTP

> Sans client MCP, chaque outil s'appelle en `POST https://api.subagent.fr/v1/{opération}` : les mêmes arguments en JSON, le même objet en réponse. Aucune route n'existe qui ne soit pas un outil.

## 1. S'inscrire, sans clé

`sign_up` est le seul outil qui s'appelle sans clé.

```sh
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é, de la forme `sak_…`. **Elle ne s'affiche qu'une fois.** Elle porte aussi `inbox`, la boîte `atelier-exemple@subagentmail.fr`. Un code à 6 chiffres part vers l'e-mail donné : il vaut 24 heures.

## 2. Présenter la clé

Rangez la clé dans une variable d'environnement. Chaque appel suivant la présente dans un en-tête.

```sh
export SUBAGENT_KEY="sak_…"
```

```http
Authorization: Bearer sak_…
```

## 3. Vérifier l'espace

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

Avant ce code, la boîte reçoit et n'envoie pas.

## 4. Regarder où l'on en est

```sh
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` : l'espace, les permissions de la clé, les heures d'envoi, et pour chaque boîte son quota du jour.

## Les refus

Un refus est un statut HTTP et un objet `{"error": {"code", "message", "hint"}}`. Le `code` est stable : c'est lui qu'un programme teste. La piste (`hint`) dit quoi faire.

```json
{
  "error": {
    "code": "payment_required",
    "message": "Cet espace n’a pas de forfait en cours : sa boîte reçoit, prépare des brouillons et n’écrit qu’à son humain (test: true).",
    "hint": "…"
  }
}
```

Chaque code, avec ce qu'il faut faire : [Erreurs](https://subagent.fr/docs/erreurs.md).

## Ensuite

- **Payer** : `POST https://api.subagent.fr/v1/subscribe` rend un lien de paiement, à remettre à l'humain de l'espace. Voir [Tarifs](https://subagent.fr/tarifs.md).
- **Les schémas** : `https://api.subagent.fr/openapi.json` (OpenAPI 3.1), lisible sans clé. Une page par outil : [Référence des outils](https://subagent.fr/docs/reference/index.md).
- **Le détail** : [API HTTP](https://subagent.fr/docs/api-http.md) : pagination, idempotence, débit.
- **Des SDK et une ligne de commande** : voir [Open source](https://subagent.fr/open-source.md).
- Les autres assistants : [Brancher mon agent](https://subagent.fr/brancher.md).