Agent quickstart: first API call

Use this flow when an agent needs a new account. If you are signing in yourself or already have a workspace, use the quickstart. Read auth.md for the machine-readable onboarding flow.

1. Register a funded account

curl -X POST https://api.impossibl.com/v1/accounts \
  -H 'content-type: application/json' \
  -d '{"email":"agent@example.com"}'

{
  "account": { "id": "acct_...", "email": "agent@example.com" },
  "api_key": "imp-rt-...",
  "balance": { "credits": 50000, "usd": 0.05 }
}

The api_key is shown once. Save it in your server environment before continuing. Use the returned balance as the authority for the starting credit amount.

export IMPOSSIBL_API_KEY="your-returned-api-key"

2. Call a model

curl --fail-with-body https://api.impossibl.com/v1/chat/completions \
  -H "Authorization: Bearer $IMPOSSIBL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello!"}],"max_tokens":128}'

Read choices[0].message.content for the answer. See the quickstart for SDK examples and common errors.

3. Watch your balance

curl https://api.impossibl.com/v1/account -H "Authorization: Bearer $IMPOSSIBL_API_KEY"
curl https://api.impossibl.com/v1/usage   -H "Authorization: Bearer $IMPOSSIBL_API_KEY"

Credits are deducted per request by token usage at the listed model prices, with no usage markup. Top-ups add a separate fixed 5% platform fee. Use POST /v1/billing/invoice before you hit zero (a 402 means the balance is insufficient for the request).

4. Hand the account to its owner

An agent-created account starts with $0.05**; once the human **claims** it (verifying their email) the account gains an extra **$1 in credits — granted once per human; disposable email domains don’t get the bonus. After creating the account, tell the user — e.g. “claim your account to verify and get $1 in credits: <link>.” Claiming also lets them sign in, manage keys, and top up. Your API key keeps working after a first claim.

# Start the ceremony with the user's email.
curl -X POST https://api.impossibl.com/agent/identity/claim \
  -H "Authorization: Bearer $IMPOSSIBL_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"email":"user@example.com"}'

{
  "status": "initiated",
  "claim_attempt": {
    "user_code": "123456",
    "interval": 5,
    "verification_uri": "https://impossibl.com/claim",
    "verification_uri_complete": "https://impossibl.com/claim?claim_attempt_token=...&user_code=123456"
  }
}

Send the user the verification_uri_complete link — the code is pre-filled, so they just sign in (as that email) and click Claim. Meanwhile, poll until claimed:

curl -X POST https://api.impossibl.com/oauth2/token \
  -H "Authorization: Bearer $IMPOSSIBL_API_KEY" \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn:workos:agent-auth:grant-type:claim'
# {"error":"authorization_pending"} -> wait `interval` seconds and retry
# {"status":"claimed","account":{...}} -> done; the account belongs to the human

Honor the returned polling interval. Stop on a terminal error or expiry; start a new claim attempt if it expires. The signed-in person’s verified email must match the email used to initiate the claim.

What happens to the workspace and key?

The first claim makes the person the workspace owner. Existing keys and credits stay in that workspace; it is not merged into another workspace they already own. A later claim initiated for another person’s email adds that person as a developer. See workspace roles.

Get started

Build

Modalities

Manage

Agent quickstart: first API call

1. Register a funded account

2. Call a model

3. Watch your balance

4. Hand the account to its owner

​1. Register a funded account

​2. Call a model

​3. Watch your balance

​4. Hand the account to its owner

1. Register a funded account

2. Call a model

3. Watch your balance

4. Hand the account to its owner