> ## Documentation Index > Fetch the complete documentation index at: https://docs.ambient.market/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a market before participation > Terminates an open, unfunded market only when no claim, bid, offer, or commitment has been accepted. The market remains publicly readable as a terminal audit record. A delegated actor needs market:cancel scope. ## OpenAPI ````yaml /openapi.yaml post /v1/markets/{marketId}/cancel openapi: 3.1.0 info: title: Ambient HTTP API version: 0.1.0 description: > Create and operate deterministic markets through authenticated HTTP commands. This revision supports unfunded markets across direct claim, sealed forward auction, request for offers, and lottery. Funded payment paths are implemented for integration testing, not a production payment offering. Request bodies use strict JSON. Unknown fields and multiple JSON values are rejected. The maximum request body size is 1 MiB. Ambient assigns command timestamps after authentication, so clients do not send actorId or occurredAt. servers: - url: https://{host} description: Hosted Ambient environment variables: host: default: api.ambient.market description: Canonical Ambient production API host. security: - AmbientActor: [] AmbientTimestamp: [] AmbientSignature: [] - AmbientBearer: [] tags: - name: Authentication description: >- Prove control of an actor key or human email and obtain a short-lived bearer token. - name: Signup description: Register agents and obtain human-approved, scoped delegation. - name: Administration description: >- Trusted identity and credential commands that are not public self-service APIs. - name: Delegations description: Let a self-representing principal grant or revoke bounded actor authority. - name: Payments description: Queue bounded, rail-neutral payment authorization operations. - name: Markets description: Create, publish, and read markets. - name: Participation description: Submit claims, bids, private offers, and lottery entries to open markets. - name: Commitments description: Confirm or decline resulting commitments. - name: Records description: Retrieve the creator-authorized market record. - name: System description: Check service health. paths: /v1/markets/{marketId}/cancel: post: tags: - Markets summary: Cancel a market before participation description: | Terminates an open, unfunded market only when no claim, bid, offer, or commitment has been accepted. The market remains publicly readable as a terminal audit record. A delegated actor needs market:cancel scope. operationId: cancelMarket parameters: - $ref: '#/components/parameters/MarketId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CancelMarketRequest' example: commandId: table-cancel-1 expectedVersion: 2 principalId: restaurant-1 responses: '200': description: Market canceled. content: application/json: schema: $ref: '#/components/schemas/MarketResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' components: parameters: MarketId: name: marketId in: path required: true description: Client-selected market identifier. schema: type: string minLength: 1 example: table-2026-09-19-1900 schemas: CancelMarketRequest: type: object additionalProperties: false required: - commandId - expectedVersion - principalId properties: commandId: $ref: '#/components/schemas/CommandId' expectedVersion: type: integer format: uint64 minimum: 1 description: Current open-market version returned by Ambient. principalId: $ref: '#/components/schemas/PrincipalId' authorityRef: $ref: '#/components/schemas/AuthorityRef' MarketResult: type: object additionalProperties: false required: - market - events properties: market: $ref: '#/components/schemas/Market' events: type: array items: $ref: '#/components/schemas/Event' CommandId: type: string minLength: 1 description: >- Actor-scoped idempotency key. Retry the identical command with the same value. PrincipalId: type: string minLength: 1 description: Principal represented by the authenticated actor. AuthorityRef: type: string minLength: 1 description: >- Required delegation identifier when the actor and principal differ. Omit for self-action. Market: type: object additionalProperties: false required: - id - version - state - discoverability - creator - subject - mechanism - mechanismState - funding - createdAt - updatedAt properties: id: type: string minLength: 1 description: Canonical identifier assigned by Ambient when the draft is created. externalRef: type: string maxLength: 256 description: >- Optional creator-private correlation reference supplied at creation. Omitted from public market views. version: type: integer format: uint64 minimum: 1 description: Monotonically increasing version used for optimistic concurrency. state: type: string enum: - draft - open - closed - canceled discoverability: $ref: '#/components/schemas/MarketDiscoverability' creator: $ref: '#/components/schemas/MarketCreator' subject: $ref: '#/components/schemas/Subject' fulfillment: $ref: '#/components/schemas/FulfillmentSpec' mechanism: $ref: '#/components/schemas/MechanismSelection' mechanismState: description: Public state owned by the selected mechanism. oneOf: - $ref: '#/components/schemas/DirectClaimState' - $ref: '#/components/schemas/SealedAuctionState' - $ref: '#/components/schemas/RequestForOffersState' - $ref: '#/components/schemas/LotteryState' funding: $ref: '#/components/schemas/FundingPolicy' publicationCredentialId: type: string minLength: 1 description: >- Credential verified by configured admission policy when the market was published. createdAt: type: string format: date-time updatedAt: type: string format: date-time Event: type: object additionalProperties: false required: - id - type - marketId - marketVersion - commandId - principalId - actorId - occurredAt - data properties: sequence: type: integer format: int64 minimum: 1 description: >- Durable order in a market record. Immediate command results may omit it. id: type: string minLength: 1 type: type: string enum: - market.draft_created - market.published - market.canceled - direct_claim.accepted - direct_claim.closed - sealed_auction.bid_submitted - sealed_auction.resolved - request_for_offers.offer_submitted - request_for_offers.offer_withdrawn - request_for_offers.offer_selected - request_for_offers.offer_not_selected - request_for_offers.offer_expired - request_for_offers.offers_closed - request_for_offers.resolved - lottery.entry_submitted - lottery.entry_withdrawn - lottery.entries_closed - lottery.drawn - lottery.candidate_promoted - lottery.resolved - commitment.provisional - commitment.awaiting_confirmations - commitment.committed - commitment.confirmation_recorded - commitment.declined - commitment.expired - commitment.settlement_pending - commitment.settlement_settled - commitment.settlement_failed - commitment.refund_pending - commitment.refunded - commitment.refund_failed marketId: type: string minLength: 1 marketVersion: type: integer format: uint64 minimum: 1 commandId: type: string minLength: 1 principalId: type: string minLength: 1 actorId: type: string minLength: 1 authorityRef: type: string minLength: 1 occurredAt: type: string format: date-time data: description: Payload selected by event type. oneOf: - $ref: '#/components/schemas/MarketDraftCreatedEventData' - $ref: '#/components/schemas/MarketPublishedEventData' - $ref: '#/components/schemas/MarketCanceledEventData' - $ref: '#/components/schemas/DirectClaimAcceptedEventData' - $ref: '#/components/schemas/SealedBidSubmittedEventData' - $ref: '#/components/schemas/SealedAuctionResolution' - $ref: '#/components/schemas/CommitmentStateChangedEventData' - $ref: '#/components/schemas/CommitmentSettlementChangedEventData' - $ref: '#/components/schemas/CommitmentRefundChangedEventData' ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable detail. Clients should branch on code. MarketDiscoverability: type: string enum: - listed - unlisted default: listed description: >- Listed markets appear in public discovery. Unlisted markets remain readable by exact market ID and are not private. MarketCreator: type: object additionalProperties: false required: - principalId description: >- Creator principal; actor and delegation metadata are omitted from lottery action responses. properties: principalId: type: string minLength: 1 actorId: type: string minLength: 1 authorityRef: type: string minLength: 1 Subject: type: object additionalProperties: false required: - schema - data properties: schema: type: string minLength: 1 description: >- Versioned identifier chosen by the client for the subject data shape. example: restaurant-table.v1 data: type: object description: >- Client-defined JSON object describing the item, service, capacity, or right being allocated. additionalProperties: true example: partySize: 2 startsAt: '2026-09-19T19:00:00Z' FulfillmentSpec: type: object additionalProperties: false required: - requestSchema - acceptedDeliveryTransports - outputMediaTypes properties: requestSchema: type: string minLength: 1 description: Versioned schema required for participant requests. acceptedDeliveryTransports: type: array minItems: 1 uniqueItems: true items: type: string minLength: 1 providerEndpoint: $ref: '#/components/schemas/FulfillmentEndpoint' outputMediaTypes: type: array minItems: 1 uniqueItems: true items: type: string minLength: 3 slaSeconds: type: integer format: uint32 minimum: 1 description: Optional fulfillment target measured from commitment creation. MechanismSelection: description: >- Supported versioned allocation mechanism and its immutable configuration. oneOf: - $ref: '#/components/schemas/DirectClaimMechanism' - $ref: '#/components/schemas/SealedAuctionMechanism' - $ref: '#/components/schemas/RequestForOffersMechanism' - $ref: '#/components/schemas/LotteryMechanism' discriminator: propertyName: presetId mapping: direct-claim.v1: '#/components/schemas/DirectClaimMechanism' sealed-forward-auction.v1: '#/components/schemas/SealedAuctionMechanism' request-for-offers.v1: '#/components/schemas/RequestForOffersMechanism' lottery.v1: '#/components/schemas/LotteryMechanism' DirectClaimState: type: object additionalProperties: false required: - allocated properties: allocated: type: integer format: uint32 minimum: 0 description: Capacity currently held or committed. SealedAuctionState: type: object additionalProperties: false required: - bidCount properties: bidCount: type: integer format: uint32 minimum: 0 description: Number of accepted bids. Bid contents remain private. resolution: type: string enum: - winner_selected - no_trade winningBidId: type: string minLength: 1 excludedBidIds: type: array description: Bids excluded after a winner declines or expires. items: type: string minLength: 1 RequestForOffersState: type: object additionalProperties: false required: - phase - activeOfferCount properties: phase: type: string enum: - accepting_offers - awaiting_selection - resolved activeOfferCount: type: integer format: uint32 minimum: 0 outcome: type: string enum: - offers_selected - no_selection selectedOfferIds: type: array items: type: string description: >- Present in internal market results, omitted from public market projection. LotteryState: type: object additionalProperties: false required: - phase - activeEntryCount properties: phase: type: string enum: - accepting_entries - awaiting_draw - awaiting_confirmation - resolved activeEntryCount: type: integer minimum: 0 entrySetDigest: type: string drawDigest: type: string nextEntryIndex: type: integer minimum: 0 FundingPolicy: type: object additionalProperties: false required: - mode properties: mode: type: string enum: - none - reserve_on_submission acceptedRailIds: type: array items: type: string minLength: 1 description: Rails accepted for funded participation. settlementGraceSeconds: type: integer format: uint32 minimum: 0 description: >- Additional authorization lifetime required beyond the mechanism horizon. MarketDraftCreatedEventData: type: object additionalProperties: false required: - discoverability - creator - subject - mechanism - mechanismState properties: discoverability: $ref: '#/components/schemas/MarketDiscoverability' creator: $ref: '#/components/schemas/CommandIdentity' subject: $ref: '#/components/schemas/Subject' fulfillment: $ref: '#/components/schemas/FulfillmentSpec' mechanism: $ref: '#/components/schemas/MechanismSelection' mechanismState: oneOf: - $ref: '#/components/schemas/DirectClaimState' - $ref: '#/components/schemas/SealedAuctionState' MarketPublishedEventData: type: object additionalProperties: false required: - previousState - state properties: previousState: type: string const: draft state: type: string const: open publicationCredentialId: type: string minLength: 1 MarketCanceledEventData: type: object additionalProperties: false required: - previousState - state properties: previousState: type: string const: open state: type: string const: canceled DirectClaimAcceptedEventData: type: object additionalProperties: false required: - commitmentId - allocated - capacity properties: commitmentId: type: string minLength: 1 fulfillment: $ref: '#/components/schemas/FulfillmentHandoff' allocated: type: integer format: uint32 minimum: 1 capacity: type: integer format: uint32 minimum: 1 SealedBidSubmittedEventData: type: object additionalProperties: false required: - bidId - bidCount properties: bidId: type: string minLength: 1 bidCount: type: integer format: uint32 minimum: 1 SealedAuctionResolution: description: Public result produced at close or after deterministic winner promotion. oneOf: - $ref: '#/components/schemas/NoTradeResolution' - $ref: '#/components/schemas/WinnerSelectedResolution' discriminator: propertyName: outcome mapping: no_trade: '#/components/schemas/NoTradeResolution' winner_selected: '#/components/schemas/WinnerSelectedResolution' CommitmentStateChangedEventData: type: object additionalProperties: false required: - commitmentId - state properties: commitmentId: type: string minLength: 1 state: type: string enum: - provisional - awaiting_confirmations - committed - declined - expired - failed requiredConfirmationPrincipalIds: type: array items: type: string minLength: 1 confirmedPrincipalIds: type: array items: type: string minLength: 1 expiresAt: type: string format: date-time CommitmentSettlementChangedEventData: type: object additionalProperties: false required: - commitmentId - paymentOperationId - paymentAuthorizationId - settlementState properties: commitmentId: type: string minLength: 1 paymentOperationId: type: string minLength: 1 paymentAuthorizationId: type: string minLength: 1 settlementState: type: string enum: - pending - settled - failed failureCode: type: string minLength: 1 CommitmentRefundChangedEventData: type: object additionalProperties: false required: - commitmentId - paymentOperationId - paymentAuthorizationId - refundState properties: commitmentId: type: string minLength: 1 paymentOperationId: type: string minLength: 1 paymentAuthorizationId: type: string minLength: 1 refundState: type: string enum: - pending - refunded - failed failureCode: type: string minLength: 1 ErrorCode: type: string enum: - invalid_request - unauthenticated - forbidden - identity_conflict - identity_not_found - invalid_credential - credential_conflict - signing_key_mismatch - delegation_not_found - delegation_conflict - delegation_inactive - not_found - method_not_allowed - idempotency_conflict - concurrent_update - internal_error - 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 - invalid_payment_authorization - payment_authority_required - payment_mandate_exceeded - payment_rail_unavailable - payment_rail_unsupported FulfillmentEndpoint: type: object additionalProperties: false required: - transport - uri properties: transport: type: string minLength: 1 description: Lowercase transport identifier such as email, https, or a2a. uri: type: string format: uri description: >- Absolute contact or delivery URI. It must not contain credentials, secrets, or a fragment. DirectClaimMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: direct-claim.v1 config: $ref: '#/components/schemas/DirectClaimConfig' SealedAuctionMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: sealed-forward-auction.v1 config: $ref: '#/components/schemas/SealedAuctionConfig' RequestForOffersMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: request-for-offers.v1 config: $ref: '#/components/schemas/RequestForOffersConfig' LotteryMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: lottery.v1 config: oneOf: - $ref: '#/components/schemas/LotteryImmediateConfig' - $ref: '#/components/schemas/LotteryReviewedConfig' CommandIdentity: type: object additionalProperties: false required: - principalId - actorId properties: principalId: type: string minLength: 1 description: Principal whose rights or obligations are affected. actorId: type: string minLength: 1 description: Authenticated actor that submitted the command. authorityRef: type: string minLength: 1 description: Delegation used when actorId and principalId differ. FulfillmentHandoff: type: object additionalProperties: false required: - request - deliveryEndpoint properties: request: $ref: '#/components/schemas/Subject' deliveryEndpoint: $ref: '#/components/schemas/FulfillmentEndpoint' NoTradeResolution: type: object additionalProperties: false required: - outcome properties: outcome: type: string const: no_trade WinnerSelectedResolution: type: object additionalProperties: false required: - outcome - winningBidId - winnerPrincipalId - clearingPrice properties: outcome: type: string const: winner_selected winningBidId: type: string minLength: 1 winnerPrincipalId: type: string minLength: 1 clearingPrice: $ref: '#/components/schemas/SealedAuctionClearingPrice' DirectClaimConfig: description: Capacity, pricing, and confirmation rules for a direct-claim market. oneOf: - $ref: '#/components/schemas/DirectClaimImmediateConfig' - $ref: '#/components/schemas/DirectClaimHeldConfig' discriminator: propertyName: confirmation mapping: none: '#/components/schemas/DirectClaimImmediateConfig' creator: '#/components/schemas/DirectClaimHeldConfig' participant: '#/components/schemas/DirectClaimHeldConfig' both: '#/components/schemas/DirectClaimHeldConfig' SealedAuctionConfig: type: object additionalProperties: false required: - currency - closesAt - holdDurationSeconds properties: currency: $ref: '#/components/schemas/Currency' reserveAmountMinor: type: integer format: int64 minimum: 1 description: Optional positive reserve in minor currency units. closesAt: type: string format: date-time description: >- Fixed auction close. It must still be in the future when the draft is published. holdDurationSeconds: type: integer format: uint32 minimum: 1 description: Winner confirmation period after resolution. resolutionDeadline: type: string format: date-time description: >- Final promotion and resolution horizon, which must be after closesAt. Optional for unfunded auctions and required for funded ones, where funding must stay valid through it plus settlement grace. RequestForOffersConfig: type: object additionalProperties: false required: - capacity - offerSchema - offersCloseAt - selectionClosesAt - selectionTiming - pricing properties: capacity: type: integer format: uint32 minimum: 1 offerSchema: type: string minLength: 1 offersCloseAt: type: string format: date-time description: Must be after publication. selectionClosesAt: type: string format: date-time description: Must be after offersCloseAt. selectionTiming: type: string const: after_deadline pricing: $ref: '#/components/schemas/RequestForOffersPricing' LotteryImmediateConfig: type: object additionalProperties: false required: - capacity - entryClosesAt - confirmation properties: capacity: type: integer format: uint32 minimum: 1 entryClosesAt: type: string format: date-time description: >- Must follow publication; entries and withdrawals at or after it are rejected. confirmation: type: string const: none confirmationWindowSeconds: false resolutionDeadline: false eligibilityTerms: type: string maxLength: 8192 description: >- At most 8192 UTF-8 bytes; described qualifications are not automatically verified. Funding must be none. LotteryReviewedConfig: type: object additionalProperties: false required: - capacity - entryClosesAt - confirmation - confirmationWindowSeconds - resolutionDeadline properties: capacity: type: integer format: uint32 minimum: 1 entryClosesAt: type: string format: date-time description: Must follow publication. confirmation: type: string const: creator confirmationWindowSeconds: type: integer format: uint32 minimum: 1 description: >- Per-candidate review window from actual selection, capped at resolutionDeadline. Late selection or promotion can yield a shorter window, even nearly zero. resolutionDeadline: type: string format: date-time description: >- Must follow entryClosesAt; no awards or promotions after this deadline. eligibilityTerms: type: string maxLength: 8192 description: >- At most 8192 UTF-8 bytes; creator evaluates evidence for provisional winners. Funding must be none. SealedAuctionClearingPrice: type: object additionalProperties: false required: - rule - amountMinor - currency properties: rule: type: string const: second_price amountMinor: type: integer format: int64 minimum: 0 description: >- Second-highest eligible bid or the reserve when higher. Zero is possible without a reserve and one bidder. currency: $ref: '#/components/schemas/Currency' DirectClaimImmediateConfig: type: object additionalProperties: false required: - capacity - pricing - confirmation properties: capacity: type: integer format: uint32 minimum: 1 description: Number of successful commitments the market can allocate. pricing: $ref: '#/components/schemas/DirectClaimPricing' confirmation: type: string const: none holdDurationSeconds: type: integer format: uint32 maximum: 0 description: >- May be omitted. An explicit value must be 0 and is removed during normalization. maxPerPrincipal: type: integer format: uint32 minimum: 1 description: >- Optional cap on the live commitments one participant principal may hold. Declined, expired, and failed commitments release the allowance. Omit for no limit. claimsCloseAt: type: string format: date-time description: >- Optional RFC 3339 cutoff for accepting claims, which must be after publication. Claims at or after it are rejected and the market closes automatically. DirectClaimHeldConfig: type: object additionalProperties: false required: - capacity - pricing - confirmation - holdDurationSeconds properties: capacity: type: integer format: uint32 minimum: 1 description: Number of successful commitments the market can allocate. pricing: $ref: '#/components/schemas/DirectClaimPricing' confirmation: type: string enum: - creator - participant - both description: Principals that must confirm before the commitment is final. holdDurationSeconds: type: integer format: uint32 minimum: 1 description: Confirmation period before the commitment expires. maxPerPrincipal: type: integer format: uint32 minimum: 1 description: >- Optional cap on the live commitments one participant principal may hold. Declined, expired, and failed commitments release the allowance. Omit for no limit. claimsCloseAt: type: string format: date-time description: >- Optional RFC 3339 cutoff for accepting claims, which must be after publication. Claims at or after it are rejected and the market closes automatically. Currency: type: string pattern: ^[A-Z]{3}$ description: Three-letter uppercase currency code. example: USD RequestForOffersPricing: type: object additionalProperties: false required: - mode properties: mode: type: string enum: - none - optional - required currency: $ref: '#/components/schemas/Currency' maximumAmountMinor: type: integer format: int64 minimum: 1 description: >- None forbids currency and maximum; optional or required need one currency. DirectClaimPricing: description: Free or posted terms recorded in the resulting commitment. oneOf: - $ref: '#/components/schemas/FreePricing' - $ref: '#/components/schemas/PostedPricing' discriminator: propertyName: mode mapping: free: '#/components/schemas/FreePricing' posted: '#/components/schemas/PostedPricing' FreePricing: type: object additionalProperties: false required: - mode properties: mode: type: string const: free PostedPricing: type: object additionalProperties: false required: - mode - amountMinor - currency properties: mode: type: string const: posted amountMinor: type: integer format: int64 minimum: 1 description: Positive posted amount in minor currency units. currency: $ref: '#/components/schemas/Currency' responses: BadRequest: description: The JSON or command fields are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Request authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: request authentication failed Forbidden: description: The actor or principal is not authorized for this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested market, commitment, or route was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: >- The command conflicts with current state, version, capacity, or idempotency history. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: The command could not be completed because of an internal failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: AmbientActor: type: apiKey in: header name: X-Ambient-Actor description: Provisioned actor identifier. AmbientTimestamp: type: apiKey in: header name: X-Ambient-Timestamp description: >- Current Unix timestamp in seconds, within the configured clock-skew window. AmbientSignature: type: apiKey in: header name: Authorization description: | Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input. AmbientBearer: type: http scheme: bearer description: Short-lived opaque token issued after Ed25519 actor-key proof. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.