POST
/v1/customersCustomers
First-class end-user primitive. Tracks spend, enforces budgets, and scopes Client Tokens. Look up an existing customer by your own ID via GET /v1/customers?external_id=… (list filter) or GET /v1/customers/ext:<external_id> (direct fetch — also works on /wallet, /usage, /conversations, /client_tokens, /margin subroutes).
Request
- HTTP
- POST
- URL
- /v1/customers
- Auth
- api_key
Try it
# Create
curl https://api.fightclub.pro/v1/customers \
-H "Authorization: Bearer $FC_API_KEY" \
-d '{"external_id":"u_42","name":"Alice","budget_usd":50}'
# Look up by your external_id (two ways)
# 1. List filter — returns {data, has_more, next_cursor}
curl "https://api.fightclub.pro/v1/customers?external_id=u_42" \
-H "Authorization: Bearer $FC_API_KEY"
# 2. Direct fetch with ext: prefix — single object, also works on subroutes
curl https://api.fightclub.pro/v1/customers/ext:u_42 \
-H "Authorization: Bearer $FC_API_KEY"
curl https://api.fightclub.pro/v1/customers/ext:u_42/wallet \
-H "Authorization: Bearer $FC_API_KEY"Parameters
| Name | Type | Description |
|---|---|---|
| external_id* | string | Your-system ID for this customer. Also usable as a list filter (?external_id=…) or as a path id prefixed with ext: (e.g. /v1/customers/ext:u_42). |
| name | string | Display name. |
| budget_usd | number | Monthly cap in USD. |
| rate_limit_rpm | integer | Per-customer requests-per-minute. |
Response fields
| Name | Type | Description |
|---|---|---|
| id | string | Customer ID (cust_*). |
| spend_usd_mtd | number | Month-to-date spend. |
Errors
- 401
invalid_api_key, Missing or revoked key. - 409
external_id_taken, You already have a customer with this external_id. - 404
not_found, No customer with that id or external_id (also returned for cross-tenant access — IDs are not enumerable).
See the full error reference.