COMPELLEAccount & credits
Developer reference

Compelle Agent API

A human funds their Compelle account once. Revocable API keys let agents commission work from that shared balance, then poll for the result—no inbox or checkout automation required.

Setup: sign in on your profile, create a key with per-order and monthly limits, and buy credits. Store the one-time secret as COMPELLE_API_KEY.

Paste this into Claude Code or Codex

Use the Compelle Agent API to commission the requested debate.

The API key is in the COMPELLE_API_KEY environment variable. Treat it as a secret: never print it, commit it, place it in a URL, or include it in logs.

1. Check GET https://compelle.com/api/agent/balance with Authorization: Bearer $COMPELLE_API_KEY.
2. Build a POST to https://compelle.com/api/agent/orders with JSON:
   {
     "service_id": "custom_debate",
     "params": {"motion": "<the question to debate>"},
     "max_price_usd": 25
   }
3. Add Authorization: Bearer $COMPELLE_API_KEY and a new random Idempotency-Key header (8–128 safe characters). Persist and reuse the same idempotency key for every retry of this exact request. Never reuse it for different input.
4. If accepted, save order_id and order_url. Run the wait as a background task and poll order_url every 5–10 seconds. Do not check email. Stop when status is fulfilled or failed.
5. On fulfilled, read result from the order response and continue the user's task. On 402, report the required and available credit. On 409 price failure, report the current quote and do not silently raise max_price_usd. On failed, report that the debit was automatically restored.

Use custom_tournament instead of custom_debate only when the user requests a tournament. Do not submit an order until the motion and maximum price are clear.

Submit an order

curl -sS https://compelle.com/api/agent/orders \
  -H "Authorization: Bearer $COMPELLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
    "service_id": "custom_debate",
    "params": {
      "motion": "Open source improves software security",
      "turns": 5
    },
    "max_price_usd": 25
  }'

max_price_usd is a caller-controlled safety ceiling, not the price. Compelle recalculates the quote server-side immediately before the atomic credit debit.

Accepted response

{
  "order_id": "…",
  "status": "paid",
  "credits_spent_usd": 4.25,
  "balance_usd": 15.75,
  "order_url": "https://compelle.com/api/order/…",
  "replayed": false
}

A new order returns 201. Retrying the identical request with the same idempotency key returns the original order with 200 and replayed: true, without a second debit.

Poll in the background

curl -sS "https://compelle.com/api/order/$ORDER_ID"

Poll every 5–10 seconds until status becomes fulfilled or failed. A fulfilled response contains result. If fulfillment fails, Compelle atomically restores the exact credit debit before returning failed.

Balance and limits

curl -sS https://compelle.com/api/agent/balance \
  -H "Authorization: Bearer $COMPELLE_API_KEY"

The response includes the shared account balance, this key’s per-order cap, its monthly cap, spend this month, and remaining monthly allowance.

Errors

StatusMeaningAgent behavior
400Invalid input or missing idempotency keyCorrect the request; do not blind-retry.
401Missing, invalid, or revoked keyStop and ask the account owner for a new key.
402Insufficient account creditsReport required_usd and balance_usd.
403Key spending limit exceeded or account on dispute holdStop; only the account owner should change limits or resolve a payment dispute.
409Quote exceeds maximum, or idempotency conflictDo not increase authorization or change a reused key silently.
429Rate limitedBack off and retry with the same idempotency key.

Security model