HTTP API overview

The HTTP API exposes typed market commands and queries as JSON plus a trusted operator provisioning command and principal-controlled delegation commands. It does not provide discovery, self-service account management, credential issuance, payment, or a user interface. Use the HTTP endpoints section in the sidebar for field types, required fields, constraints, request examples, response schemas, and status codes for each operation. The complete machine-readable contract is also available as OpenAPI YAML. Market and commitment requests require a short-lived bearer token or bootstrap HMAC authentication as described in Authentication. The challenge and token exchange routes are unsigned. Request bodies are strict JSON: unknown fields and multiple JSON values are rejected, and the maximum body size is 1 MiB. Ambient supplies authoritative command times; clients must not send occurredAt or actorId.

Routes

Method	Route	Purpose
`GET`	`/healthz`	Unsigned process health check.
`POST`	`/v1/auth/challenges`	Request a one-time challenge for a registered actor key.
`POST`	`/v1/auth/tokens`	Exchange a signed challenge for a short-lived bearer token.
`POST`	`/v1/admin/identities`	Allowlisted operator provisions a principal, actor, and first Ed25519 key.
`POST`	`/v1/delegations`	Self-representing principal grants bounded scopes to an actor.
`POST`	`/v1/delegations/{delegationId}/revoke`	Self-representing principal revokes its delegation.
`POST`	`/v1/markets`	Create a draft using a supported preset.
`POST`	`/v1/markets/{marketId}/publish`	Publish a reviewed draft.
`POST`	`/v1/markets/{marketId}/direct-claims`	Claim direct-claim capacity.
`POST`	`/v1/markets/{marketId}/sealed-bids`	Submit one private sealed bid.
`POST`	`/v1/commitments/{commitmentId}/confirm`	Confirm exact commitment terms.
`POST`	`/v1/commitments/{commitmentId}/decline`	Decline a pending commitment.
`GET`	`/v1/markets/{marketId}`	Read the current market snapshot.
`GET`	`/v1/markets/{marketId}/record`	Read the creator-authorized full record.

Command envelopes

Create-market bodies contain:

commandId, marketId, principalId, authorityRef?, subject, mechanism

Publish bodies contain:

commandId, expectedVersion, principalId, authorityRef?

Direct-claim bodies contain:

commandId, expectedVersion?, principalId, authorityRef?

Sealed-bid bodies contain:

commandId, principalId, authorityRef?, amountMinor, currency

Commitment confirmation and decline bodies contain:

commandId, principalId, authorityRef?

Path identifiers are authoritative for market and commitment actions. When the authenticated actor differs from principalId, authorityRef is required. The trusted identity-provisioning body contains:

commandId, principalId, actorId, keyId, publicKey

publicKey is an unpadded base64url Ed25519 public key. The route is mounted only when AMBIENT_OPERATOR_ACTORS configures at least one operator, and the authenticated caller must be on that allowlist. Creating distinct actor and principal IDs does not grant authority between them. Issue-delegation bodies contain:

commandId, delegationId, principalId, delegateActorId, scopes, validUntil?

Revoke-delegation bodies contain commandId and principalId; the delegation ID comes from the path. Only an authenticated actor whose ID equals principalId can manage delegations. Delegation management cannot itself be delegated in the current version.

Reads and disclosure

Any authenticated actor can read a current market snapshot. The complete record includes command inputs and decisions, commitments, events, and integrity metadata. It is restricted to the creator principal or the actor that created the market. While a sealed auction is open, bid command bodies in that creator-visible record are replaced with {"sealed":true}. Public bid receipts and events also omit the amount.

Idempotency and concurrency

Command IDs are scoped to the authenticated actor. An exact replay returns the stored decision, including a stored deterministic rejection. Reusing an ID with different content returns HTTP 409 with idempotency_conflict. Publish uses expectedVersion. Direct claims may omit it to use authoritative server arrival order. The application re-evaluates commands after bounded optimistic-concurrency conflicts so a losing allocation normally receives the authoritative deterministic rejection.

Errors

Errors use a stable envelope:

{
  "error": {
    "code": "version_conflict",
    "message": "..."
  }
}

Application rejection codes are:

invalid_command
authority_reference_required
unknown_mechanism
invalid_mechanism_config
market_not_found
commitment_not_found
principal_not_authorized
version_conflict
invalid_market_transition
invalid_commitment_transition
actor_not_authorized
capacity_exhausted

Transport and persistence failures may also return invalid_request, unauthenticated, forbidden, not_found, method_not_allowed, idempotency_conflict, concurrent_update, or internal_error. Delegation commands may additionally return identity_not_found, delegation_not_found, delegation_conflict, or delegation_inactive.

Get started

Core concepts

Reference

HTTP API overview

Routes

Command envelopes

Reads and disclosure

Idempotency and concurrency

Errors

​Routes

​Command envelopes

​Reads and disclosure

​Idempotency and concurrency

​Errors

Routes

Command envelopes

Reads and disclosure

Idempotency and concurrency

Errors