HTTP API

Complete HTTP reference with parameters. Declarative plan fields: Plan extensions. Luau hooks: Pricing.

Base URL

HTTP: https://api.hume.run · StatsD UDP: api.hume.run:8125

Common headers

Header	When	Description
`Authorization`	All except `/healthz`, `/tenants`	`Basic base64(tenant_id:api_key)`
`Content-Type`	POST/PUT bodies	`application/json`
`Idempotency-Key`	Domain writes	Required on catalog, subscription, usage, adjustment, invoice writes
`X-Bootstrap-Token`	`POST /tenants`	Required when `TENANT_CREATE_TOKEN` env is set

JSON bodies reject unknown fields. Errors return {"error":"..."}.

Entity identifiers

Entity ids use {prefix}_{ulid} (for example usr_01ARZ3NDEKTSV4RRFFQ69G5FAV). Prefixes identify the type (usr, met, pln, sub, evt, ten, whk, …); the suffix is a monotonic ULID.

Amounts

All money-like fields (monthly_price, amount, unit_amount, total, adjustments, refunds) are integers in abstract billing units. There is no currency field in the API. Display labels (USD, EUR, credits, tokens) and FX are downstream concerns.

Pagination

GET /events and GET /usage accept:

limit — max items (0 = empty page)
offset — skip from the newest end

Response shape: {"total": N, "events"|"usage": [...]}

Authentication setup

curl

01 curl -s -X POST https://api.hume.run/tenants \

02 -H 'Content-Type: application/json' \

03 -d '{"name":"Acme"}'

curl

01 AUTH_HEADER="Authorization: Basic $(printf '%s' 'ten_01ARZ3NDEKTSV4RRFFQ69G5FAV:YOUR_API_KEY' | base64)"

Endpoints

Quick reference

Method	Path	Section
GET	`/healthz`	System
POST	`/tenants`	System
GET	`/events`	Events
GET	`/state`	Events
GET/POST	`/users`	Catalog
GET/POST	`/metrics`	Catalog
GET/POST	`/features`	Catalog
GET/POST	`/plans`	Catalog
GET/PUT	`/plans/{id}/alerts`	Catalog
POST	`/pricing/packages`	Catalog
POST	`/pricing/bootstrap`	Catalog
GET/POST	`/plans/{id}/features`	Catalog
GET/POST	`/subscriptions`	Subscriptions
GET	`/subscriptions/{id}`	Subscriptions
POST	`/subscriptions/{id}/…`	Subscriptions
GET/POST	`/adjustments`	Adjustments
GET	`/refunds`	Adjustments
GET/POST	`/usage`	Usage
POST	`/entitlements/check`	Entitlements
GET	`/consumption-flags`	Entitlements
POST	`/events`	Event ingestion
POST	`/events/batch`	Event ingestion
GET/POST	`/webhooks`	Webhooks
DELETE	`/webhooks/{id}`	Webhooks
GET	`/invoices`	Invoices
POST	`/invoices/generate`	Invoices

System

GET `/healthz`

Auth	No
Success	200 — { status, time }

curl

01 curl -s https://api.hume.run/healthz

POST `/tenants`

Auth	No
Success	201 — tenant credentials

Request body

Field	Type	Req	Description
`name`	string	yes	Tenant display name

Response

{ tenant: { id, name }, api_key }

curl

01 curl -s -X POST https://api.hume.run/tenants \

02 -H 'Content-Type: application/json' \

03 -d '{"name":"Acme"}'

Rate limit: 10 requests/minute when token not configured

Events and state

GET `/events`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`limit`	int	no	Page size
`offset`	int	no	Skip from newest

Response

{ total, events[] } — audit journal, newest first (by sequence)

curl

01 curl -s 'https://api.hume.run/events?limit=100&offset=0' \

02 -H "$AUTH_HEADER"

Does not accept writes — use REST routes or POST /events for ingestion

GET `/state`

Auth	Required (Basic)
Success	200

Response

Current tenant state (users, metrics, plans, subscriptions, usage aggregates, …)

curl

01 curl -s https://api.hume.run/state \

02 -H "$AUTH_HEADER"

Catalog

GET `/users`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`external_id`	string	no	Lookup by CRM / auth system ID (unique per tenant when set)

Response

Array of user objects, or single user when external_id matches

curl

01 curl -s https://api.hume.run/users \

02 -H "$AUTH_HEADER"

04 curl -s 'https://api.hume.run/users?external_id=crm-1' \

05 -H "$AUTH_HEADER"

POST `/users`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`name`	string	yes	Display name
`email`	string	yes	Email address
`external_id`	string	no	Your CRM / auth system ID
`timezone`	string	no	IANA timezone (e.g. Europe/Berlin); drives billing period boundaries

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: user-alice' \

05 -d '{"name":"Alice","email":"alice@example.com","external_id":"crm-1"}'

GET `/users/{id}`

Auth	Required (Basic)
Success	200

Response

User object including blocked / deleted flags

curl

01 curl -s https://api.hume.run/users/usr_01ARZ3NDEKTSV4RRFFQ69G5FAV \

02 -H "$AUTH_HEADER"

POST `/users/{id}/timezone`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`timezone`	string	yes	IANA timezone (Europe/Berlin, America/New_York, …)

curl

01 curl -s -X POST https://api.hume.run/users/usr_01ARZ3NDEKTSV4RRFFQ69G5FAV/timezone \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: tz-alice' \

05 -d '{"timezone":"America/New_York"}'

Does not rewrite active subscription billing periods

POST `/users/{id}/block`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X POST https://api.hume.run/users/usr_01ARZ3NDEKTSV4RRFFQ69G5FAV/block \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: block-alice'

Suspends entitlements and subscription reads (403); usage ingest continues
Invoice admin APIs still work — see /docs/billing

POST `/users/{id}/unblock`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X POST https://api.hume.run/users/usr_01ARZ3NDEKTSV4RRFFQ69G5FAV/unblock \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: unblock-alice'

DELETE `/users/{id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/users/usr_01ARZ3NDEKTSV4RRFFQ69G5FAV \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: delete-alice'

Permanent tombstone; user hidden from GET /users list

GET `/metrics`

Auth	Required (Basic)
Success	200

Response

Array of metric definitions

curl

01 curl -s https://api.hume.run/metrics \

02 -H "$AUTH_HEADER"

POST `/metrics`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`code`	string	yes	Stable metric key (e.g. api_requests)
`name`	string	yes	Display name
`unit`	string	yes	Unit label (request, gb, …)

curl

01 curl -s -X POST https://api.hume.run/metrics \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: metric-api-requests' \

05 -d '{"code":"api_requests","name":"API Requests","unit":"request"}'

DELETE `/metrics/{id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/metrics/met_01J8ZK5BQY8XQ9R2M4V7W3N6T1 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: delete-metric-api-requests'

Returns 400 if any plan still references the metric
monthly_tracked_users cannot be deleted
Event: metric.deleted

GET `/features`

Auth	Required (Basic)
Success	200

Response

Array of feature catalog entries

curl

01 curl -s https://api.hume.run/features \

02 -H "$AUTH_HEADER"

POST `/features`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`code`	string	yes	Feature key
`name`	string	yes	Display name
`description`	string	no	Optional description

curl

01 curl -s -X POST https://api.hume.run/features \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: feature-exports' \

05 -d '{"code":"exports","name":"Exports","description":"CSV exports"}'

DELETE `/features/{id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/features/fea_01J8ZK5BQY8XQ9R2M4V7W3N6T0 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: delete-feature-exports'

Returns 400 if any plan has the feature in binding history
Event: feature.deleted

GET `/plans`

Auth	Required (Basic)
Success	200

Response

Array of plans with metric bindings

curl

01 curl -s https://api.hume.run/plans \

02 -H "$AUTH_HEADER"

POST `/plans`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`code`	string	yes	Plan key
`name`	string	yes	Display name
`monthly_price`	int	yes	Base fee in abstract units
`metrics[]`	object	yes	Bind existing metrics by metric_id
`features[]`	object	no	Optional feature bindings
`pricing_lua`	string	no	Luau plan manifest (field name is historical)
`metric_groups[]`	object	no	Shared included/tiers across metrics — see Plan extensions
`usage_pool`	object	no	Single shared included bucket for listed metrics
`classify`	object	no	JSON routes and reject rules at ingest
`limits[]`	object	no	Hard caps per metric or group (action: reject)
`alerts[]`	object	no	Threshold notifications (action: webhook) — see Plan alerts
`minimum_monthly_charge`	int	no	Top-up when subtotal is below minimum
`commitment_units`	object	no	metric_code + min usage commitment
`included_rollover`	object	no	max_periods, cap_units
`seat_pricing`	object	no	included_seats, overage_per_seat
`billing_interval`	string	no	month (default) or year
`annual_discount_percent`	int	no	0–99 when billing_interval is year
`line_labels`	object	no	base, overage invoice descriptions

curl

01 curl -s -X POST https://api.hume.run/plans \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-basic' \

05 -d '{"code":"basic","name":"Basic","monthly_price":1000,"metrics":[{"metric_id":"met_01J8ZK5BQY8XQ9R2M4V7W3N6T1","included_units":500,"tiers":[{"from":501,"to":2000,"price_per_unit":4}]}]}'

metrics[].metric_id required
tiers[] and overage_unit_price are mutually exclusive per metric
stairstep cannot combine with tiers or overage_unit_price
Full extension reference: /docs/pricing/plan-extensions

POST `/pricing/packages`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`code`	string	yes	Plan key
`name`	string	yes	Display name
`monthly_price`	int	yes	Base fee
`metrics[]`	object	yes	Creates metrics + binds to plan
`features[]`	object	no	Creates features + binds to plan
`pricing_lua`	string	no	Luau manifest — skips built-in JSON billing when set
`metric_groups[]`	object	no	Shared included/tiers across metrics — see Plan extensions
`usage_pool`	object	no	Single shared included bucket for listed metrics
`classify`	object	no	JSON routes and reject rules at ingest
`limits[]`	object	no	Hard caps per metric or group (action: reject)
`alerts[]`	object	no	Threshold notifications (action: webhook) — see Plan alerts
`minimum_monthly_charge`	int	no	Top-up when subtotal is below minimum
`commitment_units`	object	no	metric_code + min usage commitment
`included_rollover`	object	no	max_periods, cap_units
`seat_pricing`	object	no	included_seats, overage_per_seat
`billing_interval`	string	no	month (default) or year
`annual_discount_percent`	int	no	0–99 when billing_interval is year
`line_labels`	object	no	base, overage invoice descriptions

Response

{ plan, metrics[], features[], pricing? }

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: pricing-pro' \

05 -d '{"code":"pro","name":"Pro","monthly_price":2500,"metrics":[{"metric_code":"api_requests","metric_name":"API Requests","metric_unit":"request","included_units":500}],"features":[{"feature_code":"exports","feature_name":"Exports","enabled":true}]}'

metrics[].metric_id — Existing metric ID (low-level plans)
metrics[].metric_code — Metric code — creates metric in packages
metrics[].metric_name — Display name when creating via package
metrics[].metric_unit — Unit label when creating via package
metrics[].included_units — Free units per billing period
metrics[].overage_unit_price — Per-unit price after included (if no tiers)
metrics[].overage_description — Custom overage line label
metrics[].tiers[] — Volume tiers: from, to (null = open), price_per_unit
metrics[].pricing_model — stairstep or empty
metrics[].block_size — Stairstep: units per block
metrics[].block_price — Stairstep: price per block
metrics[].aggregation — Invoice window: sum (default), max, last
Without pricing_lua, built-in billing uses extension fields — see /docs/pricing/plan-extensions

POST `/pricing/bootstrap`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`plans[]`	object	yes	Array of plan definitions — same fields as /pricing/packages

curl

01 curl -s -X POST https://api.hume.run/pricing/bootstrap \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: bootstrap-v1' \

05 -d '{"plans":[{"code":"free","price":0,"metrics":{"api_requests":{"included":1000}}},{"code":"pro","price":5000,"metrics":{"api_requests":{"included":100000,"overage":1}},"features":["exports"]}]}'

Compact syntax supported: price (alias for monthly_price), metrics as map code→{included, overage}, features as string[]
Shared metrics created once and reused across plans
See /docs/pricing — bootstrap example

DELETE `/plans/{id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: delete-plan-basic'

Returns 400 if any subscription references the plan (current plan_id or pending_change)
After delete the plan code can be reused
Event: plan.deleted

Plan edit (unused plans only)

When no subscription references a plan, you can remove metrics/features and manage ingest limits. Removing a metric also clears groups, pool, limits, classify, commitment, and seat bindings for that code.

DELETE `/plans/{id}/metrics/{metric_id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/metrics/met_01J8ZK5BQY8XQ9R2M4V7W3N6T1 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: plan-drop-metric'

Event: plan.metric_removed

DELETE `/plans/{id}/features/{feature_id}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/features/fea_01J8ZK5BQY8XQ9R2M4V7W3N6T0 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: plan-drop-feature'

Clears binding history entry; event: plan.feature_removed

GET `/plans/{id}/limits`

Auth	Required (Basic)
Success	200

Response

Current limits[] on the plan

curl

01 curl -s https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/limits \

02 -H "$AUTH_HEADER"

POST `/plans/{id}/limits`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`scope`	string	yes	metric \| metric_group
`metric_code`	string	no	When scope is metric
`group`	string	no	When scope is metric_group
`max_per_period`	int	yes	Hard cap in current subscription period
`action`	string	yes	reject (only supported action)

curl

01 curl -s -X POST https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/limits \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-add-limit' \

05 -d '{"scope":"metric","metric_code":"api_requests","max_per_period":50000,"action":"reject"}'

Appends a limit; event: plan.limits_updated

PUT `/plans/{id}/limits`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`limits[]`	object	yes	Replace entire limits array

curl

01 curl -s -X PUT https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/limits \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-set-limits' \

05 -d '[{"scope":"metric_group","group":"tokens","max_per_period":1000000,"action":"reject"}]'

PUT `/plans/{id}/limits/{index}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`scope`	string	yes	metric \| metric_group
`max_per_period`	int	yes	Updated cap
`action`	string	yes	reject

curl

01 curl -s -X PUT https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/limits/0 \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-update-limit' \

05 -d '{"scope":"metric","metric_code":"api_requests","max_per_period":80000,"action":"reject"}'

DELETE `/plans/{id}/limits/{index}`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X DELETE https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/limits/0 \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: plan-remove-limit'

Plan alerts

Alerts emit a durable usage.threshold_crossed event once per billing period when usage crosses percent of the baseline. Baseline is baseline_units if set, else a matching hard limits[].max_per_period, else included_units. Engine action is always webhook — email and other side effects belong to receivers. Allowed on plans that are already in use.

GET `/plans/{id}/alerts`

Auth	Required (Basic)
Success	200

Response

Current alerts[] on the plan

curl

01 curl -s https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/alerts \

02 -H "$AUTH_HEADER"

PUT `/plans/{id}/alerts`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`scope`	string	yes	metric \| metric_group
`metric_code`	string	no	When scope is metric
`group`	string	no	When scope is metric_group
`percent`	int	yes	1–100; fire when period usage crosses this % of baseline
`baseline_units`	int	no	Optional explicit baseline; otherwise limit or included_units
`action`	string	no	webhook (default)

curl

01 curl -s -X PUT https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/alerts \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-set-alerts' \

05 -d '[{"scope":"metric","metric_code":"api_requests","percent":80,"baseline_units":100,"action":"webhook"}]'

Body is a JSON array replacing the entire alerts list; event: plan.alerts_updated

GET `/plans/{id}/features`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`at`	RFC3339	no	Point-in-time feature bindings

curl

01 curl -s 'https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/features?at=2026-07-20T12:00:00Z' \

02 -H "$AUTH_HEADER"

POST `/plans/{id}/features`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`feature_code`	string	no	Feature code (or feature_id)
`feature_id`	string	no	Feature ID alternative
`enabled`	bool	yes	Grant or revoke
`effective_from`	RFC3339	no	Delayed activation

curl

01 curl -s -X POST https://api.hume.run/plans/pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0/features \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: plan-exports' \

05 -d '{"feature_code":"exports","enabled":true}'

Subscriptions

GET `/subscriptions`

Auth	Required (Basic)
Success	200

Response

All subscriptions with current lifecycle state

curl

01 curl -s https://api.hume.run/subscriptions \

02 -H "$AUTH_HEADER"

GET `/subscriptions/{id}`

Auth	Required (Basic)
Success	200 / 404

Response

Single subscription snapshot at current time

curl

01 curl -s https://api.hume.run/subscriptions/sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3 \

02 -H "$AUTH_HEADER"

POST `/subscriptions`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`user_id`	string	yes	Billable user
`plan_id`	string	yes	Plan to subscribe to
`trial_days`	int	no	Trial length (mutually exclusive with trial_ends_at)
`trial_ends_at`	RFC3339	no	Explicit trial end

curl

01 curl -s -X POST https://api.hume.run/subscriptions \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: sub-1' \

05 -d '{"user_id":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","plan_id":"pln_01J8ZK5BQY8XQ9R2M4V7W3N6T0","trial_days":14}'

POST `/subscriptions/{id}/change-plan`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`plan_id`	string	yes	Target plan
`policy`	string	yes	prorate_immediately \| refund_immediately \| effective_next_cycle

Response

{ subscription, adjustment?, refund? }

curl

01 curl -s -X POST https://api.hume.run/subscriptions/sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3/change-plan \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: change-1' \

05 -d '{"plan_id":"pln_01J8ZK5BQY8XQ9R2M4V7W3N6T4","policy":"prorate_immediately"}'

prorate_immediately → separate adjustment.posted (kind: prorate)
refund_immediately → separate refund.issued for unused time credit
effective_next_cycle → subscription.plan_change_scheduled

POST `/subscriptions/{id}/pause`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X POST https://api.hume.run/subscriptions/sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3/pause \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: pause-1'

No request body
Paused time excluded from base fee

POST `/subscriptions/{id}/resume`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

curl

01 curl -s -X POST https://api.hume.run/subscriptions/sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3/resume \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: resume-1'

POST `/subscriptions/{id}/cancel-at-period-end`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Query parameters

Field	Type	Req	Description
`enabled`	bool	no	true (default) to cancel at period end; false to clear

curl

01 curl -s -X POST 'https://api.hume.run/subscriptions/sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3/cancel-at-period-end?enabled=true' \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: cancel-1'

Adjustments and refunds

Manual billing corrections are first-class events, not embedded fields on other records. Amounts are signed integers in billing units (negative = credit, positive = charge). There is no currency code. kind: prorate (plan change), credit, debit (manual; inferred from sign if omitted). They appear as invoice lines when created_at falls inside the invoice window.

POST `/adjustments`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`subscription_id`	string	yes	Subscription to adjust
`amount`	int	yes	Signed amount in abstract units (negative = credit)
`kind`	string	no	prorate \| credit \| debit (inferred from sign if omitted)
`description`	string	yes	Line description on invoice

Response

Adjustment record — emits adjustment.posted

curl

01 curl -s -X POST https://api.hume.run/adjustments \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: adj-1' \

05 -d '{"subscription_id":"sub_01J8ZK5BQY8XQ9R2M4V7W3N6T3","amount":-500,"kind":"credit","description":"Goodwill credit"}'

Response fields: id, subscription_id, user_id, amount, description, source_event_id?, created_at
Plan changes with refund_immediately append refund.issued automatically (amount always positive; invoice line is negative)

GET `/adjustments`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`user_id`	string	no	Filter by user (optional)

Response

Array of adjustment records

curl

01 curl -s 'https://api.hume.run/adjustments?user_id=usr_01ARZ3NDEKTSV4RRFFQ69G5FAV' \

02 -H "$AUTH_HEADER"

GET `/refunds`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`user_id`	string	no	Filter by user (optional)

Response

Array of refund records — fields: id, subscription_id, user_id, amount, reason, source_event_id?, created_at

curl

01 curl -s 'https://api.hume.run/refunds?user_id=usr_01ARZ3NDEKTSV4RRFFQ69G5FAV' \

02 -H "$AUTH_HEADER"

Usage

GET `/usage`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`user_id`	string	no	Filter by user
`metric_id`	string	no	Filter by metric
`from`	RFC3339	no	Range start (inclusive)
`to`	RFC3339	no	Range end (exclusive)
`limit`	int	no	Pagination
`offset`	int	no	Pagination (newest first)

Response

{ total, usage[] }

curl

01 curl -s 'https://api.hume.run/usage?user_id=usr_01ARZ3NDEKTSV4RRFFQ69G5FAV&limit=50' \

02 -H "$AUTH_HEADER"

POST `/usage`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`user_id`	string	yes	User consuming the metric
`metric_id`	string	yes	Metric ID
`quantity`	int	yes	Units consumed
`created_at`	RFC3339	no	Event time; max +24h in future

curl

01 curl -s -X POST https://api.hume.run/usage \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: usage-1' \

05 -d '{"user_id":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","metric_id":"met_01J8ZK5BQY8XQ9R2M4V7W3N6T1","quantity":150}'

Shorthand for usage.recorded event
Plan may apply JSON classify, limits, then Luau classify before commit — metric may be rerouted or rejected with 400

Entitlements

POST `/entitlements/check`

Auth	Required (Basic)
Success	200

Request body

Field	Type	Req	Description
`user_id`	string	yes	User to check
`feature_code`	string	no	Feature key (or feature_id)
`feature_id`	string	no	Feature ID alternative
`at`	RFC3339	no	Defaults to now

Response

{ allowed, reason, subscription_status, plan_id, checked_at, … }

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":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","feature_code":"exports"}'

GET `/consumption-flags`

Auth	Required (Basic)
Success	200

Query parameters

Field	Type	Req	Description
`user_id`	string	yes	User to inspect
`at`	RFC3339	no	Historical point-in-time

Response

Flags: usage.near_limit, usage.over_limit, usage.current_tier

curl

01 curl -s 'https://api.hume.run/consumption-flags?user_id=usr_01ARZ3NDEKTSV4RRFFQ69G5FAV' \

02 -H "$AUTH_HEADER"

Event ingestion (optional)

For normal use, prefer the dedicated REST routes (POST /users, POST /usage, …). POST /events is a generic envelope if an external system prefers one JSON shape. For usage.recorded, POST /usage is equivalent and simpler. POST /events/batch accepts many events in one request, with a per-item result (207 if some rows failed).

POST `/events`

Auth	Required (Basic)
Success	202 Accepted

Request body

Field	Type	Req	Description
`event_id`	string	yes	Idempotency key for the log
`type`	string	yes	Event type (see table below)
`source`	string	yes	Originating system
`occurred_at`	RFC3339	yes	When it happened; max +24h in future
`data`	object	yes	Type-specific payload

curl

01 curl -s -X POST https://api.hume.run/events \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -d '{"event_id":"evt_01J8ZK5BQY8XQ9R2M4V7W3N6T5","type":"usage.recorded","source":"api","occurred_at":"2026-07-01T12:00:00Z","data":{"user_id":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","metric_code":"api_requests","quantity":42}}'

Catalog events (user.created, metric.created, …) create entities — e.g. user.created requires data.user_name and data.user_email; data.user_id is stored as external_id

POST `/events/batch`

Auth	Required (Basic)
Success	202 / 207 Multi-Status

Request body

Field	Type	Req	Description
`events[]`	EventInput	yes	Array of events, applied sequentially

Response

{ results: [{ index, record? } | { index, error }], accepted, failed } — HTTP 207 if any row failed

curl

01 curl -s -X POST https://api.hume.run/events/batch \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -d '{"events":[{"event_id":"evt_01J8ZK5BQY8XQ9R2M4V7W3N6T5","type":"usage.recorded","source":"api","occurred_at":"2026-07-01T12:00:00Z","data":{"user_id":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","metric_id":"met_01J8ZK5BQY8XQ9R2M4V7W3N6T1","quantity":5}}]}'

Event types

Writable types for POST /events and POST /events/batch:

type	REST equivalent	Notes
`user.created`	`POST /users`	requires data.user_name, data.user_email
`user.blocked`	`POST /users/{id}/block`	suspends read access; usage ingest continues
`user.unblocked`	`POST /users/{id}/unblock`	restores read access
`user.deleted`	`DELETE /users/{id}`	permanent tombstone
`user.timezone_updated`	`POST /users/{id}/timezone`	IANA timezone for local billing
`metric.created`	`POST /metrics`	—
`metric.deleted`	`DELETE /metrics/{id}`	only when no plan references the metric
`feature.created`	`POST /features`	—
`feature.deleted`	`DELETE /features/{id}`	only when no plan binding history references the feature
`plan.created`	`POST /plans`	—
`plan.deleted`	`DELETE /plans/{id}`	only when no subscription references the plan
`plan.metric_removed`	`DELETE /plans/{id}/metrics/{metric_id}`	only when plan has no subscriptions
`plan.feature_removed`	`DELETE /plans/{id}/features/{feature_id}`	clears binding history; plan must have no subscriptions
`plan.limits_updated`	`PUT/POST /plans/{id}/limits`, `PUT/DELETE …/limits/{index}`	replace, add, update, or remove ingest limits on unused plans
`plan.alerts_updated`	`PUT /plans/{id}/alerts`	replace threshold alerts (allowed on plans in use)
`plan.feature_enabled`	`POST /plans/{id}/features`	enabled: true
`plan.feature_disabled`	`POST /plans/{id}/features`	enabled: false
`usage.recorded`	`POST /usage`	—
`usage.threshold_crossed`	(side effect of usage + plan alerts)	once per period per alert when crossing percent of baseline
`subscription.created`	`POST /subscriptions`	—
`subscription.plan_changed`	`POST …/change-plan`	may emit adjustment.posted or refund.issued
`subscription.plan_change_scheduled`	change-plan effective_next_cycle	—
`subscription.paused`	`POST …/pause`	—
`subscription.resumed`	`POST …/resume`	—
`subscription.cancel_at_period_end_set`	cancel-at-period-end enabled=true	—
`subscription.cancel_at_period_end_cleared`	cancel-at-period-end enabled=false	—
`adjustment.posted`	`POST /adjustments`	manual or plan-change proration
`refund.issued`	(side effect of refund plan change)	credit for unused subscription time

Lifecycle events

Emitted automatically on subscription state transitions (not writable via public REST):

type	When
`subscription.activated`	Trial ends or subscription becomes billable
`subscription.canceled`	Subscription is canceled (immediate or at period end)
`subscription.period_rolled`	Billing period advances

Webhooks

Register an outbound URL per tenant. On each committed event, the service POSTs the EventRecord JSON asynchronously. Failed deliveries retry 3 times with a 2s pause.

GET `/webhooks`

Auth	Required (Basic)
Success	200

Response

{ webhooks: WebhookEndpoint[] } — id, url, events, created_at (secret is never returned)

curl

01 curl -s https://api.hume.run/webhooks \

02 -H "$AUTH_HEADER"

POST `/webhooks`

Auth	Required (Basic)
Success	201

Request body

Field	Type	Req	Description
`url`	string	yes	http or https endpoint URL
`events`	string[]	yes	Event types to forward, or ["*"] for all
`secret`	string	no	HMAC signing secret; server generates one if omitted

Response

WebhookEndpoint + secret — secret is returned only in this response

curl

01 curl -s -X POST https://api.hume.run/webhooks \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -d '{"url":"https://your-app.example/webhooks/billing","events":["subscription.created","subscription.canceled"]}'

Same event types as GET /events (user.created, usage.recorded, subscription.canceled, …)

DELETE `/webhooks/{id}`

Auth	Required (Basic)
Success	204 / 404

curl

01 curl -s -X DELETE https://api.hume.run/webhooks/whk_01J8ZK5BQY8XQ9R2M4V7W3N6T2 \

02 -H "$AUTH_HEADER"

Delivery payload

Each delivery is a POST with Content-Type: application/json. The body is the committed EventRecord — the same shape as entries in GET /events.

json

{
  "sequence": 12,
  "event_id": "evt_01J8ZK5BQY8XQ9R2M4V7W3N6T5",
  "type": "subscription.created",
  "source": "http",
  "occurred_at": "2026-07-01T12:00:00Z",
  "accepted_at": "2026-07-01T12:00:00Z",
  "data": { "...": "..." },
  "result": { "subscription": { "...": "..." } }
}

Signature verification

POST /webhooks returns a secret once. Store it on the receiver and verify every delivery before processing. Each delivery includes:

Header	Meaning
`Billing-Webhook-Signature`	`t=<unix>,v1=<hex>`

Compute v1 = HMAC-SHA256(secret, "<unix>.<raw body>") and compare with a constant-time function. Reject requests older than ~5 minutes (replay protection).

On retry the body and signature timestamp are identical — deduplicate by event_id and return 2xx without re-processing duplicates.

Subscribable event types

events lists event types to forward, or ["*"] for all. The same types as in the event types apply, including lifecycle events:

type	When
`user.created`	User created
`user.blocked`	User suspended (non-payment)
`user.unblocked`	User restored
`user.deleted`	User permanently removed
`metric.created`	Metric created
`feature.created`	Feature created
`plan.created`	Plan created
`plan.feature_enabled` / `plan.feature_disabled`	Plan feature binding changed
`usage.recorded`	Usage recorded (HTTP, StatsD, or synthetic)
`usage.threshold_crossed`	Plan alert threshold crossed (once per period)
`plan.alerts_updated`	Plan alerts replaced
`subscription.created`	Subscription created
`subscription.plan_changed`	Plan changed immediately
`subscription.plan_change_scheduled`	Plan change queued for next cycle
`subscription.paused` / `subscription.resumed`	Pause / resume
`subscription.cancel_at_period_end_set` / `subscription.cancel_at_period_end_cleared`	Cancel-at-period-end toggled
`subscription.activated`	Trial ended or subscription became billable
`subscription.canceled`	Subscription canceled
`subscription.period_rolled`	Billing period advanced
`adjustment.posted`	Adjustment recorded
`refund.issued`	Refund recorded
`invoice.generated`	Draft invoice created
`invoice.finalized`	Invoice amounts locked
`invoice.paid`	Payment recorded
`invoice.voided`	Invoice voided

Invoices

GET `/invoices`

Auth	Required (Basic)
Success	200

Response

Array of invoices (draft, finalized, paid, void)

curl

01 curl -s https://api.hume.run/invoices \

02 -H "$AUTH_HEADER"

GET `/invoices/{id}`

Auth	Required (Basic)
Success	200

Response

Single invoice

curl

01 curl -s https://api.hume.run/invoices/inv_01ARZ3NDEKTSV4RRFFQ69G5FAV \

02 -H "$AUTH_HEADER"

POST `/invoices/generate`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	201

Request body

Field	Type	Req	Description
`user_id`	string	yes	Billable user
`period_start`	RFC3339	yes	Invoice window start
`period_end`	RFC3339	yes	Invoice window end (exclusive)

Response

Draft invoice JSON with line items in abstract units

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: invoice-jan' \

05 -d '{"user_id":"usr_01ARZ3NDEKTSV4RRFFQ69G5FAV","period_start":"2026-07-01T00:00:00Z","period_end":"2026-08-01T00:00:00Z"}'

Status is draft — finalize before collection
Invoices for any window, including past months — period rollover does not break historical calculations
adjustment.posted and refund.issued in window → type: adjustment / refund lines (refunds are negative amounts)
Base fee proportional to active time — trials and pauses excluded; plan segments billed separately
Usage billed within periods; included_units and tier boundaries scaled for partial windows
Same metric across multiple subscriptions for one user billed once
Plans with Luau pricing replace built-in lines per billing period
Plans without Luau pricing use JSON billing (groups, pools, tiers, stairstep, seats, minimum, commitment) — see Plan extensions
Classify (JSON or Luau) runs only at usage ingest, not during invoicing

POST `/invoices/{id}/finalize`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Response

Invoice with status finalized

curl

01 curl -s -X POST https://api.hume.run/invoices/inv_01ARZ3NDEKTSV4RRFFQ69G5FAV/finalize \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: invoice-jan-finalize'

Works while user is blocked — tenant admin only

POST `/invoices/{id}/mark-paid`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Request body

Field	Type	Req	Description
`payment_ref`	string	yes	PSP reference (e.g. stripe_pi_…)

Response

Invoice with status paid

curl

01 curl -s -X POST https://api.hume.run/invoices/inv_01ARZ3NDEKTSV4RRFFQ69G5FAV/mark-paid \

02 -H 'Content-Type: application/json' \

03 -H "$AUTH_HEADER" \

04 -H 'Idempotency-Key: invoice-jan-paid' \

05 -d '{"payment_ref":"stripe_pi_3ABC"}'

Call after PSP confirms payment; works while user is blocked

POST `/invoices/{id}/void`

Auth	Required (Basic)
Idempotency-Key	Required header
Success	200

Response

Invoice with status void

curl

01 curl -s -X POST https://api.hume.run/invoices/inv_01ARZ3NDEKTSV4RRFFQ69G5FAV/void \

02 -H "$AUTH_HEADER" \

03 -H 'Idempotency-Key: invoice-jan-void'

Draft or finalized only — not paid

StatsD ingestion

UDP packet format:

text

billing.<tenant_id>.<api_key>.user.<user_id>.<metric_code>:<value>|c

curl

01 printf 'billing.ten_01ARZ3NDEKTSV4RRFFQ69G5FAV.sk_live_xxx.user.usr_01ARZ3NDEKTSV4RRFFQ69G5FAV.api_requests:42|c\n' | nc -w1 -u api.hume.run 8125

|g gauge type also accepted — value is still treated as usage quantity. Optional idempotency tag: |#event_id:evt-123.

HTTP API

Base URL

Common headers

Entity identifiers

Amounts

Pagination

Authentication setup

Endpoints

Quick reference

System

GET /healthz

POST /tenants

Events and state

GET /events

GET /state

Catalog

GET /users

POST /users

GET /users/{id}

POST /users/{id}/timezone

POST /users/{id}/block

POST /users/{id}/unblock

DELETE /users/{id}

GET /metrics

POST /metrics

DELETE /metrics/{id}

GET /features

POST /features

DELETE /features/{id}

GET /plans

POST /plans

POST /pricing/packages

POST /pricing/bootstrap

DELETE /plans/{id}

Plan edit (unused plans only)

DELETE /plans/{id}/metrics/{metric_id}

DELETE /plans/{id}/features/{feature_id}

GET /plans/{id}/limits

POST /plans/{id}/limits

PUT /plans/{id}/limits

PUT /plans/{id}/limits/{index}

DELETE /plans/{id}/limits/{index}

Plan alerts

GET /plans/{id}/alerts

PUT /plans/{id}/alerts

GET /plans/{id}/features

POST /plans/{id}/features

Subscriptions

GET /subscriptions

GET /subscriptions/{id}

POST /subscriptions

POST /subscriptions/{id}/change-plan

POST /subscriptions/{id}/pause

POST /subscriptions/{id}/resume

POST /subscriptions/{id}/cancel-at-period-end

Adjustments and refunds

POST /adjustments

GET /adjustments

GET /refunds

Usage

GET /usage

POST /usage

Entitlements

POST /entitlements/check

GET /consumption-flags

Event ingestion (optional)

POST /events

POST /events/batch

Event types

Lifecycle events

Webhooks

GET /webhooks

POST /webhooks

DELETE /webhooks/{id}

Delivery payload

Signature verification

Subscribable event types

Invoices

GET /invoices

GET /invoices/{id}

GET `/healthz`

POST `/tenants`

GET `/events`

GET `/state`

GET `/users`

POST `/users`

GET `/users/{id}`

POST `/users/{id}/timezone`

POST `/users/{id}/block`

POST `/users/{id}/unblock`

DELETE `/users/{id}`

GET `/metrics`

POST `/metrics`

DELETE `/metrics/{id}`

GET `/features`

POST `/features`

DELETE `/features/{id}`

GET `/plans`

POST `/plans`

POST `/pricing/packages`

POST `/pricing/bootstrap`

DELETE `/plans/{id}`

DELETE `/plans/{id}/metrics/{metric_id}`

DELETE `/plans/{id}/features/{feature_id}`

GET `/plans/{id}/limits`

POST `/plans/{id}/limits`

PUT `/plans/{id}/limits`

PUT `/plans/{id}/limits/{index}`

DELETE `/plans/{id}/limits/{index}`

GET `/plans/{id}/alerts`

PUT `/plans/{id}/alerts`

GET `/plans/{id}/features`

POST `/plans/{id}/features`

GET `/subscriptions`

GET `/subscriptions/{id}`

POST `/subscriptions`

POST `/subscriptions/{id}/change-plan`

POST `/subscriptions/{id}/pause`

POST `/subscriptions/{id}/resume`

POST `/subscriptions/{id}/cancel-at-period-end`

POST `/adjustments`

GET `/adjustments`

GET `/refunds`

GET `/usage`

POST `/usage`

POST `/entitlements/check`

GET `/consumption-flags`

POST `/events`

POST `/events/batch`

GET `/webhooks`

POST `/webhooks`

DELETE `/webhooks/{id}`

GET `/invoices`

GET `/invoices/{id}`

POST `/invoices/generate`

POST `/invoices/{id}/finalize`

POST `/invoices/{id}/mark-paid`

POST `/invoices/{id}/void`