Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Authorization: Bearer hk_live_... for live keys or Authorization: Bearer hk_test_... for test-mode keys. hk_test_ keys resolve real public catalog metadata but return deterministic committed fixtures, never call inference, and never mutate live credits. This is the only transport for the credential: the x-api-key alias once documented was removed in 0.2.0, because the edge authorizer reads Authorization as its single identity source and a request on any other header is refused before it is authenticated.

Never accepted on a dashboardJwt operation, and there are no exceptions. GET /v1/usage and GET /v1/limits briefly declared both schemes (0.8.0); that was withdrawn in 0.8.1 because no deployed route could honor it — both operations are served by the control-plane API, whose authorizer verifies a Cognito token and refuses an hk_live_ credential on shape, and the customer API does not route either path. An API-key holder reads its balance and reservation from QuoteResponse, which carries balance_credits and reserved_credits on every quote. Every operation in this document takes one scheme or the other and refuses the wrong one as unauthenticated.

Headers

​
Idempotency-Key
string
required

As IdempotencyKeyHeader, but required: a confirm spends up to a whole selection's ceiling, and a retry that could not be recognized as one would spend it twice. Missing is 400 invalid_request.

Required string length: 1 - 255
Pattern: ^[!-~]{1,255}$

Path Parameters

​
quote_id
string
required

Opaque, server-generated quote identifier.

Maximum string length: 40
Pattern: ^qte_[A-Za-z0-9]{16,32}$

Body

application/json

The quote is in the path and the key is in the header, so the body carries at most the spending fence below. An empty object, or no body at all, is accepted; any other property is refused, so a further field can be added without an old client having silently sent it.

​
expected_total_credits
integer

The quote's total_ceiling_credits as the caller read it. Sent, and disagreeing with the quote's own total, the API refuses the confirm with 409 expected_total_mismatch before an enclosure is probed or a credit is reserved: a caller that has misread the price cannot spend it. Omitted, the confirm proceeds on the quote's recorded total alone.

Required range: 0 <= x <= 9007199254740991

Response

The job group this confirm created, complete, with every member named — or, on a repeat under the same Idempotency-Key, the original group as it stands.

One group's rollup. member_count is how many members the confirm set out to create; members is how many exist, which is fewer only while the group is pending (or after it was abandoned part way). credits_reserved is what the group still holds against the balance — the reservations of members not yet terminal; credits_settled is what it has been charged, job members and cache reads together; credits_released is what came back from members that failed, were cancelled, or settled below their ceiling. None of the three is a bill: each job member carries its own figures, and the ledger is the record.

​
group_id
string
required

Opaque, server-generated job group identifier.

Maximum string length: 40
Pattern: ^grp_[A-Za-z0-9]{16,32}$
​
status
enum<string>
required

pending while a confirm is still fanning out (or died doing so); complete once every member landed; abandoned once the sweeper returned a pending group's reservations past its deadline. A cancelled group is complete with cancelled members.

Available options:
pending,
complete,
abandoned
​
quote_id
required

The quote this group confirmed, or null for a single-episode submission.

Maximum string length: 40
Pattern: ^qte_[A-Za-z0-9]{16,32}$
​
member_count
integer
required
Required range: x >= 1
​
members
object[]
required
Maximum array length: 100

One member of a group — a job, or a settled cache read. kind discriminates.

​
member_counts
object
required

How many members are in each job state, plus how many were settled cache reads (which have no state — they were delivered at confirm). The nine sum to member_count on a complete group.

​
credits_reserved
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
​
credits_settled
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
​
credits_released
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
​
created_at
string<date-time>
required
​
completion_deadline
string<date-time>
required

Past this, a still-pending group is swept.

​
completed_at
required

An ISO 8601 timestamp, or null.

​
abandoned_at
required

An ISO 8601 timestamp, or null.