Read the capacity tree of one merchant date

GET

/capacity-pools

const url = 'https://quikstik-core.fly.dev/capacity-pools?date=2026-04-15';
const options = {
  method: 'GET',
  headers: {
    'x-tenant-id': '2489E9AD-2EE2-8E00-8EC9-32D5F69181C0',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://quikstik-core.fly.dev/capacity-pools?date=2026-04-15' \
  --header 'Authorization: Bearer <token>' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0'

Read-back twin of POST /capacity-pools. Returns every pool on the merchant civil date with its parent, target, derived committed, remaining, allowance and limit, ordered root → leaves. A pool belongs to a date by key: date:{variant}@{date} and win:{label}@{date} end in @{date}, and the undated dep:{departure} leaves are reached as their descendants.

limit is target + allowance exactly as the capacity gate computes it (the ceiling a commit is refused at); remaining is the target-based figure the storefront may advertise (capacity_pool_state), so the two differ by exactly the allowance. committed is the derived subtree sum, so a window and a date show their leaves rolled up.

Auth: a session, or an operator key scoped capacity.read. Optional pool_key narrows to that pool and its ancestors; a key outside the date answers an empty list. A date nobody provisioned is 200 with pools: [], never 404.

Authorizations

bearerAuth

Parameters

Header Parameters

x-tenant-id

required

string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Query Parameters

date

required

string format: date

Merchant civil date, YYYY-MM-DD.

pool_key

string

One pool and its ancestors.

Responses

200

The tree for the date (possibly empty)

application/json

object

date

required

string format: date

pools

required

Array<object>

object

pool_key

required

string

parent_key

required

string

nullable

target

required

integer

committed

required

integer

remaining

required

Target-based, floored at 0.

integer

allowance_kind

required

string

Allowed values: fixed percent

allowance_value

required

integer

limit

required

Target + allowance, as the gate computes it.

integer

Example

{
  "pools": [
    {
      "allowance_kind": "fixed"
    }
  ]
}

401

Invalid_session / unauthenticated

403

Operator key without the capacity.read scope (insufficient_scope)

422

Invalid_date (missing or not YYYY-MM-DD)

application/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

503

Capacity backend unavailable