[HUME]
Start free

Quickstart

End-to-end flow in curl: tenant → catalog → user → subscription → usage → entitlement check → invoice. For plan shapes, see Recipes first. Base URL: https://api.hume.run. All money fields are integers in abstract billing units (no currency code).

1. Create a tenant

Public by default (10 req/min). Response includes tenant.id and api_key.

curl
01 curl -s -X POST https://api.hume.run/tenants \
02 -H 'Content-Type: application/json' \
03 -d '{"name":"Acme"}'

2. Authenticate

Save credentials from step 1, then set the auth header for all following requests:

curl
01 TENANT_ID="ten_01ARZ3NDEKTSV4RRFFQ69G5FAV" # from response
02 API_KEY="sk_live_..." # from response
03
04 AUTH_HEADER="Authorization: Basic $(printf '%s' "$TENANT_ID:$API_KEY" | base64)"

3. Define catalog (pricing package)

One call creates metrics, features, and a plan. Example payloads by use case: Recipes. Field reference: Plan extensions.

curl
01 curl -s -X POST https://api.hume.run/pricing/packages \
02 -H 'Content-Type: application/json' \
03 -H "$AUTH_HEADER" \
04 -H 'Idempotency-Key: quickstart-catalog' \
05 -d '{
06 "code": "pro",
07 "name": "Pro",
08 "monthly_price": 2500,
09 "metrics": [{
10 "metric_code": "api_requests",
11 "metric_name": "API Requests",
12 "metric_unit": "request",
13 "included_units": 1000,
14 "overage_unit_price": 2
15 }],
16 "features": [{
17 "feature_code": "exports",
18 "feature_name": "Exports",
19 "enabled": true
20 }]
21 }'

Save plan.id and metrics[0].id from the response.

4. Create a user

curl
01 curl -s -X POST https://api.hume.run/users \
02 -H 'Content-Type: application/json' \
03 -H "$AUTH_HEADER" \
04 -H 'Idempotency-Key: quickstart-user' \
05 -d '{"name":"Alice","email":"alice@example.com","external_id":"crm-1"}'

Save user.id (e.g. usr_01ARZ3NDEKTSV4RRFFQ69G5FAV).

5. Subscribe the user

curl
01 PLAN_ID="pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0" # from step 3
02 USER_ID="usr_01ARZ3NDEKTSV4RRFFQ69G5FAV" # from step 4
03
04 curl -s -X POST https://api.hume.run/subscriptions \
05 -H 'Content-Type: application/json' \
06 -H "$AUTH_HEADER" \
07 -H 'Idempotency-Key: quickstart-sub' \
08 -d '{"user_id":"'"$USER_ID"'","plan_id":"'"$PLAN_ID"'","trial_days":14}'

6. Record usage

HTTP for domain events; StatsD UDP for high-frequency metering — see StatsD.

curl
01 METRIC_ID="met_01J8ZK5BQY8XQ9R2M4V7W3N6T1" # from step 3
02
03 curl -s -X POST https://api.hume.run/usage \
04 -H 'Content-Type: application/json' \
05 -H "$AUTH_HEADER" \
06 -H 'Idempotency-Key: quickstart-usage-1' \
07 -d '{"user_id":"'"$USER_ID"'","metric_id":"'"$METRIC_ID"'","quantity":1500}'

7. Check entitlement

curl
01 curl -s -X POST https://api.hume.run/entitlements/check \
02 -H 'Content-Type: application/json' \
03 -H "$AUTH_HEADER" \
04 -d '{"user_id":"'"$USER_ID"'","feature_code":"exports"}'

8. Generate an invoice

Produces JSON line items for a billing window — pass them to your payment layer.

curl
01 curl -s -X POST https://api.hume.run/invoices/generate \
02 -H 'Content-Type: application/json' \
03 -H "$AUTH_HEADER" \
04 -H 'Idempotency-Key: quickstart-invoice-jul' \
05 -d '{
06 "user_id":"'"$USER_ID"'",
07 "period_start":"2026-07-01T00:00:00Z",
08 "period_end":"2026-08-01T00:00:00Z"
09 }'

Next steps

  • Recipes — more plan scenarios (tiers, seats, peak/off-peak, caps)
  • Webhooks — react to billing events in your app
  • Subscriptions — plan changes, pause, cancel-at-period-end
  • HTTP API — full endpoint reference
  • Concepts — tenants, entities, identifiers