Connect over HTTP

1. Sign up, without a key

sign_up is the only tool called without a key.

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

The response carries api_key: the key, of the form sak_…. It is shown only once. It also carries inbox, the inbox [email protected]. A 6-digit code goes to the e-mail given: it is valid for 24 hours.

2. Present the key

Store the key in an environment variable. Every following call presents it in a header.

export SUBAGENT_KEY="sak_…"

Authorization: Bearer sak_…

3. Verify the space

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

Before this code, the inbox receives but does not send.

4. See where you stand

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

The response is the object the tool returns over MCP in structuredContent: the space, the key’s permissions, the sending hours, and for each inbox its daily quota.

Refusals

A refusal is an HTTP status and an object {"error": {"code", "message", "hint"}}. The code is stable: it is what a program tests. The lead (hint) says what to do. The message is in French, as the server writes it.

{
  "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": "…"
  }
}

Every code, with what to do: Errors.

Next

• Pay: POST https://api.subagent.fr/v1/subscribe returns a payment link, to hand to the space’s human. See Pricing.
• The schemas: https://api.subagent.fr/openapi.json (OpenAPI 3.1), readable without a key. One page per tool: Tool reference.
• The details: HTTP API: pagination, idempotency, rate.
• SDKs and a command line: see Open source.
• The other assistants: Connect my agent.