Connect an agent

An agent (an LLM, script, or bot) obtains a scoped API key through an OAuth-style device flow, then calls the API on your behalf — without ever seeing your login.

API base URL

Point your agent at this base URL.

https://api.proposal.clouted.com

Agent starts the flow

The agent requests a device + user code. It shows you the user_code (or the full authorize link).

request

curl -X POST https://api.proposal.clouted.com/agent/setup \
  -H "Content-Type: application/json" \
  -d '{"name": "Proposal Bot"}'

response

{
  "device_code": "long-opaque-string",
  "user_code": "ABCD-1234",
  "authorize_url": "https://api.proposal.clouted.com/agent/authorize?code=ABCD-1234",
  "expires_in": 300,
  "poll_interval": 3
}

You approve in the browser

Open the authorize link (or go to the home page and enter the code), sign in with Rally, and approve. The approval page reads the agent name via GET /agent/code/{user_code} and approves via POST /agent/approve.

Agent polls for the key

The agent polls until you approve. The raw key is returned exactly once.

request

curl -X POST https://api.proposal.clouted.com/agent/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "long-opaque-string"}'

{"status":"pending"} — keep polling (respect poll_interval)
{"status":"complete","api_key":"pb_..."} — store it securely
{"status":"expired"} — the 5-minute window lapsed; start over

Agent uses the API

Send the key as X-API-Key (or Authorization: Bearer pb_...) on every request.

discover leads

curl https://api.proposal.clouted.com/proposals/leads \
  -H "X-API-Key: pb_..."

generate from a lead

curl "https://api.proposal.clouted.com/proposals/generate?record_id=opp_XXXX" \
  -H "X-API-Key: pb_..."

generate from a brief

curl -X POST https://api.proposal.clouted.com/proposals/from-brief \
  -H "X-API-Key: pb_..." \
  -H "Content-Type: application/json" \
  -d '{"company": "Acme Records", "client_type": "music", "budget_usd": 40000}'

Security

Keys are scoped to the approving user; the agent acts as you.
Keys are hashed at rest — only the pb_XXXXXXXX prefix is stored in the clear.
Agents can't mint more agents — approval requires a real browser session.
Device codes expire in 5 minutes. Revoke keys anytime.