# relais — an inbox your agent can block on

Ephemeral and local agents have no public URL, so they can't RECEIVE anything —
OAuth callbacks, 'your job finished' webhooks, payment confirmations, human
approvals. relais gives your agent a URL that catches any HTTP request, and a
long-poll it can block on until something lands. No crypto, no OAuth, all curl.
Base URL: https://relais.intrane.fr

## The whole thing in 3 curls

1. Make an inbox (save the token — shown once):
   curl -s -X POST https://relais.intrane.fr/v1/inboxes -d '{"label":"my oauth callback"}'
   -> {"inbox_id":"in_..","token":"rk_..","catch_url":"https://relais.intrane.fr/c/in_.."}
2. Give catch_url to whatever should reach you (an OAuth redirect_uri, a webhook
   config, a form action, another agent). Anything sent there is captured.
3. Block until it arrives (or read the backlog):
   curl -s https://relais.intrane.fr/v1/wait -H 'Authorization: Bearer rk_..'     # blocks ~25s
   curl -s https://relais.intrane.fr/v1/messages -H 'Authorization: Bearer rk_..' # the backlog

## Persistent inboxes (peage)

A free inbox is ephemeral (expires in 1h, 100 messages) — perfect for a one-shot
OAuth dance. Need a STABLE URL to register with a provider (Stripe/GitHub webhook,
an OAuth app)? Pay for a persistent inbox (30-day TTL, 10000 messages) for 5 cents
with a peage wallet. Full path if you don't have a wallet yet (paid via https://peage.intrane.fr):
   1. mint a wallet:  curl -s -X POST https://peage.intrane.fr/v1/wallets -d '{}'   (save the pw_ token)
   2. fund it:        curl -s -X POST https://peage.intrane.fr/v1/topup -H 'Authorization: Bearer pw_..' -d '{"amount_cents":500}'
                      -> a Stripe Checkout URL; hand it to your human, they pay once
   3. buy the inbox:  curl -s -X POST https://relais.intrane.fr/v1/inboxes -H 'X-Peage-Wallet: pw_..' -d '{"label":"stripe prod"}'
   peage is the pay-per-call rail for agents (https://peage.intrane.fr/llms.txt); relais is one of its merchants.

## Endpoints

POST   /v1/inboxes {email?, label?}              -> {inbox_id, token, catch_url}  (X-Peage-Wallet = persistent)
ANY    /c/<inbox_id>                             -> capture a request (this is catch_url; public)
GET    /v1/messages       Bearer <token>         -> up to 50 captured messages (marks them read)
GET    /v1/wait           Bearer <token>         -> long-poll: block until one new message (?timeout_ms=, max 55000)
DELETE /v1/messages       Bearer <token>         -> clear read messages
DELETE /v1/inbox          Bearer <token>         -> delete the inbox
GET    /_health                                  -> liveness

A captured message is {id, method, path, headers, body, ip, received_at}. Secrets
(Authorization, Cookie) are NOT stored; the body is capped at 60 KB.