Skip to main content
The HTTP API exposes typed market and payment-authorization commands and market queries as JSON, plus self-service signup, trusted operator provisioning, and principal-controlled delegation commands. It also provides configured-issuer credential issuance, status lookup, and revocation. The first launch is unfunded across four market presets, including Lottery. Payment authorization and settlement are implemented integration paths, but principal-bound Connect onboarding and production rail reconciliation are not complete. The API does not provide private-market access policy, key rotation, or portable VCs. Human signup has no hosted UI yet; public market browsing can use the read-only console. 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. The OAuth connection endpoints are documented separately. The OpenAPI contract describes bearer authentication for market requests; OAuth discovery, consent, and token exchange use the separate authorization endpoints. The resulting access token authenticates HTTP and MCP requests. Listed published-market discovery, exact-ID snapshots, and public activity are unsigned. An unlisted market is omitted from discovery but remains readable by exact ID; unlisted is not an access-control boundary. Market IDs are deterministically derived identifiers rather than secrets and must not be treated as credentials. Market and commitment commands plus creator records require a short-lived bearer token or bootstrap HMAC authentication as described in Authentication. The challenge and token exchange routes are also 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

Private reads accept optional principalId and authorityRef query parameters. Omit both when acting for yourself. A delegated agent supplies the principal it represents and its current delegation; revocation or a disabled identity denies the private read. RFO offer reads use market:offer_select for the requester and market:offer_submit for a provider’s own offers. Full-record reads remain limited to the creator principal or the original creating actor with current market:create authority. Lottery entry, withdrawal and own-outcome reads require market:lottery_enter. Candidate review requires creator commitment:confirm authority; declining requires commitment:decline and a recorded reason. The existing confirm and decline endpoints apply the lottery’s rules. There is no public draw or seed endpoint. OAuth connections must explicitly consent to the new entry scope.

​
Command envelopes

Create-market bodies contain:
Ambient assigns the canonical marketId and returns it with the draft. An optional externalRef lets the creator correlate the market with another system; it is private, nonunique, and not an idempotency key. Exact retries use the actor-scoped commandId. Publish bodies contain:
Direct-claim bodies contain:
Sealed-bid bodies contain:
RFO submit, withdraw, and selection bodies contain, respectively:
GET /v1/markets/{marketId}/offers requires authentication and current principal authority. The requester sees all private offers, a provider sees only its own, and other actors receive the public market state with an empty offer list. Offer views omit actor and delegation references. The first RFO preset is unfunded. Commitment confirmation, decline, and refund bodies contain:
Decline also accepts reason: required for lottery creator decline, optional for other presets. It must be valid UTF-8, at most 2048 bytes, without surrounding whitespace. Lottery confirm/decline responses and exact retries redact private mechanism digests and alternate positions.

​
Lottery commands and review

entryId is the opaque ID returned by your own outcome read. Entries and withdrawals must arrive before entryClosesAt; the same principal cannot keep two active entries. Wrong-preset entry/withdrawal commands return 404, as do wrong-preset review reads. evidenceUrl is an HTTPS URL without credentials or surrounding whitespace, valid UTF-8 and at most 2048 bytes. URLs are not unique and are not fetched or verified. Configuration eligibilityTerms is at most 8192 UTF-8 bytes after trimming. Payment-authorization bodies contain:
paymentCredential is required only by rails that declare private authorization material. For Stripe it is a seller-scoped Link Shared Payment Token. Ambient encrypts it for the payment worker and never includes it in the decision journal, payment status, market record, or canonical authorization. Path identifiers are authoritative for market and commitment actions. When the authenticated actor differs from principalId, authorityRef is required. Refund requires the market creator or an active delegation with commitment:refund. It queues a full refund asynchronously. The agreement remains committed, and inventory is not reopened; refund progress is visible on the commitment as pending, refunded, or failed. A terminally failed refund may be retried with a new command ID, which creates a new payment operation and preserves the failed attempt in the record. An optional market fulfillment specification publishes the required request schema, accepted delivery transports, output media types, optional provider endpoint, and SLA. Claims against such a market must include a private fulfillment handoff containing a matching {schema, data} request and a delivery {transport, uri}. Ambient snapshots both into the commitment terms. Public discovery exposes the specification, while public activity omits the participant request and delivery URI. Endpoint URIs must never contain bearer tokens, embedded credentials, or other secrets. Ambient does not invoke these endpoints or track delivery completion. The trusted identity-provisioning body contains:
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:
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. The payment:authorize scope requires both validUntil and a paymentMandate. The mandate fixes one rail, one currency, and a positive per-authorization maximum; it may additionally restrict the payee and market. It is deliberately not an aggregate spending budget. A mandate without the scope, or the scope without a mandate, is rejected. Payment-authorization bodies contain:
The authenticated payer, or an actor holding the cited payment:authorize delegation, may queue the command. Delegated requests must remain within the mandate and cannot outlive the delegation. Ambient checks the configured rail’s declared authorization and currency capabilities before queueing. A successful response is 202 Accepted with a PaymentOperation in pending state; the workflow worker performs the asynchronous rail call. For delegated requests, the database transaction that queues the operation locks and revalidates the delegation, scope, revocation state, active window, and mandate. It also limits the delegation to one pending, leased, or unexpired authorized hold. An exact accepted retry still replays after later revocation. The actor that queued an authorization can poll GET /v1/payment-operations/{commandId}. Command IDs remain actor-scoped, so another actor receives the same 404 as a missing operation. The returned PaymentOperationView includes status, current verified authorization state when available, stable rejection code, rail ID, and timestamps. It excludes raw requests/results, provider error text, rail references, lease mechanics, and journal entries. Deployments may configure the in-memory fake rail, which moves no money, and the opt-in Stripe Connect card adapter verified in sandbox. Rail availability is deployment-specific. Credential-issuance bodies contain:
The authenticated actor must equal the actor configured in AMBIENT_CREDENTIAL_ISSUER. The issuer, signing key, and issue time cannot be supplied by the client. The subject and registered issuer key must already exist. Exact retries return the originally signed credential. Credential reads and revocations are restricted to that same configured issuing actor. Revocation bodies contain commandId; Ambient supplies the credential ID from the path and the revocation time. Revocation decisions are durable and idempotent. revokedAt is authoritative registry status and does not alter the immutable signed issuance payload. When AMBIENT_CREDENTIAL_ADMISSION contains a rule for the draft’s subject schema, publication must include credentialId. Ambient verifies the trusted issuer, subject principal, credential type, validity window, revocation status, registered signing key, and signature before opening the market. The accepted market and publication event retain the verified credential ID.

​
Reads and disclosure

Anyone can list and inspect published markets without authenticating. Drafts are never returned and are indistinguishable from missing markets. Public market projections expose the creator principal, subject, mechanism rules, safe mechanism state, funding requirements, credential instructions, and timestamps. They omit creating actors, authority references, credential IDs, private bid, offer and lottery entry IDs, commands, commitments and payment records. GET /v1/markets orders published markets by updatedAt and market ID, both descending. limit defaults to 50 and may be set from 1 through 100. Pass the opaque nextCursor value back as cursor to continue. GET /v1/markets/{marketId}/activity returns the safe public timeline. It may include lifecycle types, counts, states, outcomes, and clearing prices. It does not disclose actor or participant identities, command bodies, bid or offer identifiers, commitment identifiers, payment references, or failure details. GET /v1/markets/{marketId}/my-outcome requires authentication and current claim, bid, offer-submission or lottery-entry authority for the represented principal. It returns that principal’s accepted bid receipts, offer states, lottery entry history and commitments alongside the public market snapshot. It does not reveal other participants’ private activity. An empty commitment list is not necessarily a final loss while auction or creator-reviewed lottery promotion remains possible. The complete record includes command inputs and decisions, commitments, events, and integrity metadata. It remains restricted to the creator principal or the original creating actor with current market:create authority. For an open lottery, this endpoint returns 403 even to its creator. Use the candidate review endpoint while reviews are open; the complete verified audit becomes available after resolution, including expired or unawarded outcomes. 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. Payment-operation status is restricted to the authenticated actor that queued the command. It is a redacted operational projection, not a payment receipt or global payment-history query.

​
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:
Application rejection codes are:
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. Credential administration may additionally return credential_not_found or credential_inactive. Payment authorization may additionally return invalid_payment_authorization, payment_authority_required, payment_mandate_exceeded, payment_rail_unavailable, or payment_rail_unsupported.