> ## 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.

# Confirm a commitment

> Records confirmation from a principal listed in
requiredConfirmationPrincipalIds before expiresAt.




## OpenAPI

````yaml /openapi.yaml post /v1/commitments/{commitmentId}/confirm
openapi: 3.1.0
info:
  title: Ambient HTTP API
  version: 0.1.0
  description: >
    Create and operate deterministic markets through signed HTTP commands.


    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.example.com
        description: API host supplied with your provisioned credentials.
security:
  - AmbientActor: []
    AmbientTimestamp: []
    AmbientSignature: []
  - AmbientBearer: []
tags:
  - name: Authentication
    description: >-
      Prove control of a registered actor key and obtain a short-lived bearer
      token.
  - name: Administration
    description: Trusted operator commands that are not public self-service APIs.
  - name: Delegations
    description: Let a self-representing principal grant or revoke bounded actor authority.
  - name: Markets
    description: Create, publish, and read markets.
  - name: Participation
    description: Submit claims and sealed bids 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/commitments/{commitmentId}/confirm:
    post:
      tags:
        - Commitments
      summary: Confirm a commitment
      description: |
        Records confirmation from a principal listed in
        requiredConfirmationPrincipalIds before expiresAt.
      operationId: confirmCommitment
      parameters:
        - $ref: '#/components/parameters/CommitmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitmentActionRequest'
            example:
              commandId: table-confirm-1
              principalId: diner-1
      responses:
        '200':
          description: Confirmation recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketActionResult'
        '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:
    CommitmentId:
      name: commitmentId
      in: path
      required: true
      description: Commitment identifier returned by an allocation action.
      schema:
        type: string
        minLength: 1
  schemas:
    CommitmentActionRequest:
      type: object
      additionalProperties: false
      required:
        - commandId
        - principalId
      properties:
        commandId:
          $ref: '#/components/schemas/CommandId'
        principalId:
          $ref: '#/components/schemas/PrincipalId'
        authorityRef:
          $ref: '#/components/schemas/AuthorityRef'
    MarketActionResult:
      type: object
      additionalProperties: false
      required:
        - market
        - commitments
        - events
      properties:
        market:
          $ref: '#/components/schemas/Market'
        commitments:
          type: array
          description: Commitments created or changed by the command.
          items:
            $ref: '#/components/schemas/Commitment'
        bidReceipts:
          type: array
          description: Amount-free receipts returned after accepted sealed bids.
          items:
            $ref: '#/components/schemas/SealedBidReceipt'
        auctionResolution:
          $ref: '#/components/schemas/SealedAuctionResolution'
        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
        - creator
        - subject
        - mechanism
        - mechanismState
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          minLength: 1
        version:
          type: integer
          format: uint64
          minimum: 1
          description: Monotonically increasing version used for optimistic concurrency.
        state:
          type: string
          enum:
            - draft
            - open
            - closed
        creator:
          $ref: '#/components/schemas/CommandIdentity'
        subject:
          $ref: '#/components/schemas/Subject'
        mechanism:
          $ref: '#/components/schemas/MechanismSelection'
        mechanismState:
          description: Public state owned by the selected mechanism.
          oneOf:
            - $ref: '#/components/schemas/DirectClaimState'
            - $ref: '#/components/schemas/SealedAuctionState'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Commitment:
      type: object
      additionalProperties: false
      required:
        - id
        - version
        - marketId
        - marketVersion
        - creatorPrincipalId
        - participantPrincipalId
        - state
        - terms
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          minLength: 1
        version:
          type: integer
          format: uint64
          minimum: 1
        marketId:
          type: string
          minLength: 1
        marketVersion:
          type: integer
          format: uint64
          minimum: 1
        creatorPrincipalId:
          type: string
          minLength: 1
        participantPrincipalId:
          type: string
          minLength: 1
        state:
          type: string
          enum:
            - provisional
            - awaiting_confirmations
            - committed
            - declined
            - expired
            - failed
        terms:
          description: Immutable terms generated by the market mechanism.
          oneOf:
            - $ref: '#/components/schemas/DirectClaimCommitmentTerms'
            - $ref: '#/components/schemas/SealedAuctionCommitmentTerms'
        requiredConfirmationPrincipalIds:
          type: array
          items:
            type: string
            minLength: 1
        confirmedPrincipalIds:
          type: array
          items:
            type: string
            minLength: 1
        expiresAt:
          type: string
          format: date-time
          description: Confirmation deadline when the commitment is awaiting confirmation.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SealedBidReceipt:
      type: object
      additionalProperties: false
      required:
        - bidId
        - marketId
        - marketVersion
        - state
        - submittedAt
      properties:
        bidId:
          type: string
          minLength: 1
        marketId:
          type: string
          minLength: 1
        marketVersion:
          type: integer
          format: uint64
          minimum: 1
        state:
          type: string
          const: active
        submittedAt:
          type: string
          format: date-time
    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:
            $ref: '#/components/schemas/NoTradeResolution'
          winner_selected:
            $ref: '#/components/schemas/WinnerSelectedResolution'
    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
            - direct_claim.accepted
            - sealed_auction.bid_submitted
            - sealed_auction.resolved
            - commitment.provisional
            - commitment.awaiting_confirmations
            - commitment.committed
            - commitment.confirmation_recorded
            - commitment.declined
            - commitment.expired
        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/DirectClaimAcceptedEventData'
            - $ref: '#/components/schemas/SealedBidSubmittedEventData'
            - $ref: '#/components/schemas/SealedAuctionResolution'
            - $ref: '#/components/schemas/CommitmentStateChangedEventData'
    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.
    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.
    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'
    MechanismSelection:
      description: >-
        Supported versioned allocation mechanism and its immutable
        configuration.
      oneOf:
        - $ref: '#/components/schemas/DirectClaimMechanism'
        - $ref: '#/components/schemas/SealedAuctionMechanism'
      discriminator:
        propertyName: presetId
        mapping:
          direct-claim.v1:
            $ref: '#/components/schemas/DirectClaimMechanism'
          sealed-forward-auction.v1:
            $ref: '#/components/schemas/SealedAuctionMechanism'
    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
    DirectClaimCommitmentTerms:
      type: object
      additionalProperties: false
      required:
        - subject
        - pricing
      properties:
        subject:
          $ref: '#/components/schemas/Subject'
        pricing:
          $ref: '#/components/schemas/DirectClaimPricing'
    SealedAuctionCommitmentTerms:
      type: object
      additionalProperties: false
      required:
        - subject
        - winningBidId
        - pricing
      properties:
        subject:
          $ref: '#/components/schemas/Subject'
        winningBidId:
          type: string
          minLength: 1
        pricing:
          $ref: '#/components/schemas/SealedAuctionClearingPrice'
    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'
    MarketDraftCreatedEventData:
      type: object
      additionalProperties: false
      required:
        - creator
        - subject
        - mechanism
        - mechanismState
      properties:
        creator:
          $ref: '#/components/schemas/CommandIdentity'
        subject:
          $ref: '#/components/schemas/Subject'
        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
    DirectClaimAcceptedEventData:
      type: object
      additionalProperties: false
      required:
        - commitmentId
        - allocated
        - capacity
      properties:
        commitmentId:
          type: string
          minLength: 1
        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
    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
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - unauthenticated
        - forbidden
        - identity_conflict
        - identity_not_found
        - 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
    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'
    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:
            $ref: '#/components/schemas/FreePricing'
          posted:
            $ref: '#/components/schemas/PostedPricing'
    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'
    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:
            $ref: '#/components/schemas/DirectClaimImmediateConfig'
          creator:
            $ref: '#/components/schemas/DirectClaimHeldConfig'
          participant:
            $ref: '#/components/schemas/DirectClaimHeldConfig'
          both:
            $ref: '#/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.
    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'
    Currency:
      type: string
      pattern: ^[A-Z]{3}$
      description: Three-letter uppercase currency code.
      example: USD
    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.
    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.
  responses:
    BadRequest:
      description: The JSON or command fields are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: HMAC 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.

````