> ## 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. # Get a market > Returns the current market snapshot to any authenticated actor. ## OpenAPI ````yaml /openapi.yaml get /v1/markets/{marketId} 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/markets/{marketId}: get: tags: - Markets summary: Get a market description: Returns the current market snapshot to any authenticated actor. operationId: getMarket parameters: - $ref: '#/components/parameters/MarketId' responses: '200': description: Current market snapshot. content: application/json: schema: $ref: '#/components/schemas/Market' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '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: 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 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 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. 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' 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 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. 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. Currency: type: string pattern: ^[A-Z]{3}$ description: Three-letter uppercase currency code. example: USD 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' 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: Unauthorized: description: HMAC authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: request authentication failed NotFound: description: The requested market, commitment, or route was not found. 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. ````