> ## Documentation Index > Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt > Use this file to discover all available pages before exploring further. # Get a role-filtered private auction view > Reads the live owner first and falls back to the shared completed projection. Existence of a private auction is opaque to unrelated principals: they receive the same 404 as a caller asking for an ID that was never issued. ## OpenAPI ````yaml /openapi/agora.yaml get /v1/auctions/{auctionID} openapi: 3.1.0 info: title: Agora Auction House API version: 1.0.0-pilot description: | Private first-price sealed auctions for venue-backed prediction contracts. Active auctions are never published through an unauthenticated or global feed. All price and quantity values are integer atoms. ## Authentication Every `/v1` operation requires a first-party Kairos session JWT (`Authorization: Bearer `, RS256, `iss: kairos.trade`, `aud: kairos-api`, `ver: 1`, an expiry claim, and a subject enrolled in the Auction House). Any other credential shape — missing header, wrong audience, revoked session, unenrolled subject — is rejected with `401` before the handler runs. There is no API-key or anonymous tier. Browser WebSocket clients pass the same JWT as the `Sec-WebSocket-Protocol` subprotocol pair `authorization, Bearer.`. Every session is granted the `auction:create` and `auction:quote` capabilities; they only allow the request to reach the fail-closed Go-owned economic policy store, which remains the real authorization boundary. ## Errors Every error body is a flat JSON object: `{"error": ""}`, plus a `"message"` field on rejections raised by the auction engine. Codes are stable; `message` is descriptive and must not be parsed. `422` rejections carry the durable auction reason code (for example `INVALID_PRICE_TICK`, `UNAUTHORIZED_SIZE`, `SERVICE_CAPACITY_EXCEEDED`) as the `error` value. ## Request limits Request bodies are capped at 1 MiB (`413 payload_too_large`). JSON is parsed strictly: no `null` values, no duplicate object keys, no unknown fields, no trailing data, and at most 64 levels of nesting. Owner-routing headers (`X-Service-Token`, `X-Agora-Peer`, `X-Agora-Active-Only`, `X-Agora-Owner-Read-Fallback`) are internal capabilities and are rejected with `403` on the public listener. ## Rate limiting Only state-changing operations are metered, by a per-account and per-auction token bucket owned by the authoritative shard, evaluated before any risk reservation or journal write. Exceeding a bucket returns `429 auction_mutation_rate_limited`. No `Retry-After` or `X-RateLimit-*` headers are emitted; back off and retry with the same idempotency key. Reads, both preflight calls, and the stream are not metered. servers: - url: https://agora.kairos.trade description: >- Production. Agora is allow-listed RFQ and the production host is not currently enabled, so this base URL does not answer public requests yet. - url: https://staging-agora.kairos.trade description: Staging. security: - bearerAuth: [] paths: /v1/auctions/{auctionID}: parameters: - $ref: '#/components/parameters/AuctionID' get: summary: Get a role-filtered private auction view description: | Reads the live owner first and falls back to the shared completed projection. Existence of a private auction is opaque to unrelated principals: they receive the same 404 as a caller asking for an ID that was never issued. responses: '200': description: Originator or invited-MM view headers: X-Agora-Completed-As-Of: description: >- Present only when the view was served from the shared completed projection; RFC 3339 nanosecond projection time. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/AuctionView' '400': $ref: '#/components/responses/InvalidAuctionID' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InternalRoutingHeaders' '404': description: >- Auction absent or not visible to the caller; private-auction existence is opaque '503': description: | `completed_projection_unavailable` when the shared projection cannot be read, or `auction_owner_unavailable` / `owner_routing_unavailable` / `owner_response_invalid` when the owning shard for this auction cannot be reached. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: AuctionID: name: auctionID in: path required: true description: Canonical UUID whose first character is the owner shard (0, 1, or 2). schema: type: string format: uuid schemas: AuctionView: type: object required: - auction description: Fields are filtered by originator/invitee role and identity policy. properties: auction: $ref: '#/components/schemas/Auction' originator_identity: type: string description: >- Policy-authorized public program selector; never a program, execution-account, venue-account, or credential identifier. audience_participant_ids: type: array description: >- Originator-only policy-authorized public counterparty selectors; hidden execution identities never cross this boundary. items: type: string own_quote: $ref: '#/components/schemas/Quote' allocations: type: array items: $ref: '#/components/schemas/Allocation' Error: type: object required: - error description: | Flat error envelope used by every JSON error response. `message` is present on rejections raised by the auction engine and absent on transport-level rejections such as `invalid_list_page` or `payload_too_large`. Match on `error`; never parse `message`. properties: error: type: string description: Stable machine-readable code or the durable auction reason code on a 422/409 rejection.: null message: type: string description: Human-readable detail; not a stable contract. Auction: type: object description: | Role-filtered auction state. Reserve, slippage, fallback, and public benchmark fields are present only for the originator. properties: auction_id: type: string format: uuid owner_epoch: type: string pattern: ^(0|[1-9]\d*)$ description: >- Opaque unsigned owner-generation counter; compare as a decimal string. customer_class: type: string market_id: type: string outcome_id: type: string side: enum: - BUY - SELL fill_instruction: enum: - FOK - FLEXIBLE min_fill_quantity_atoms: type: integer format: int64 target_fill_quantity_atoms: type: integer format: int64 max_fill_quantity_atoms: type: integer format: int64 objective_mode: enum: - STOP_AT_TARGET - SEEK_MAXIMUM allocation_priority_policy: enum: - PRICE_FIRST - COMPLETION_FIRST execution_objective_quantity_atoms: type: integer format: int64 filled_quantity_atoms: type: integer format: int64 hard_reserve_price_atoms: $ref: '#/components/schemas/PriceAtoms' slippage_reference_price_atoms: $ref: '#/components/schemas/PriceAtoms' slippage_reference_policy: enum: - PUBLIC_EXECUTABLE_VWAP - APPROVED_EXPLICIT max_cumulative_slippage_bps: type: integer format: int64 minimum: 0 maximum: 10000 minimum_private_improvement_bps: type: integer format: int64 minimum: 0 maximum: 10000 maximum_mm_concentration_bps: type: integer format: int64 minimum: 1 maximum: 10000 minimum_mm_reliability_tier: enum: - UNRATED - C - B - A public_benchmark_price_atoms: $ref: '#/components/schemas/PriceAtoms' public_benchmark_quantity_atoms: type: integer format: int64 minimum: 1 public_benchmark_observed_at: type: string format: date-time public_benchmark_source: type: string benchmark_calculation_version: type: string max_total_execution_time_ms: type: integer format: int64 minimum: 1 venue_scope: type: array items: type: string audience_mode: enum: - MANUAL - SAVED_GROUP - RECOMMENDED max_recipients: type: integer minimum: 1 maximum: 16 identity_disclosure_mode: enum: - CLASS_ONLY - REVEAL_TO_INVITEES - REVEAL_ON_AWARD fallback_ladder: type: array items: $ref: '#/components/schemas/FallbackRung' rule_profile: $ref: '#/components/schemas/RuleProfile' client_metadata: type: object additionalProperties: type: string description: >- Catalog labels are participant-visible. The optional client_order_id is returned only to the originator for OMS reconciliation. invitation_delivery: allOf: - $ref: '#/components/schemas/InvitationDelivery' description: Originator-only durable delivery summary. state: enum: - PENDING_INVITATIONS - OPEN - CLOSING - EXECUTING - RECONCILING - PROCESSING - FILLED - PARTIALLY_FILLED - UNFILLED - CANCELLED - FAILED - COMPLETED description: >- PROCESSING is an invitee-only privacy projection used after close while another participant's execution or reconciliation state remains hidden. final_reason: enum: - OBJECTIVE_REACHED - TARGET_NOT_REACHED - MAXIMUM_NOT_REACHED - INSUFFICIENT_SIZE - MIN_FILL_NOT_REACHABLE - NO_BIDS - RESERVE_NOT_MET - MIN_BLOCK_SIZE_NOT_MET - REFERENCE_UNAVAILABLE - NO_PRIVATE_IMPROVEMENT - NO_ELIGIBLE_QUOTES - USER_CANCELLED - AUCTION_OWNER_LOST - MINIMUM_TRANCHE_BROKEN - BROKEN_FOK - EXECUTION_UNKNOWN - RECONCILIATION_REQUIRED - LADDER_EXHAUSTED - CANCEL_REMAINDER - RUNG_UNAVAILABLE - RUNG_QUOTE_STALE - RUNG_MINIMUM_NOT_REACHED - RUNG_SLIPPAGE_BREACH - VENUE_REJECTED - EXECUTION_REJECTED - EXECUTION_TIMEOUT - WINNER_EXPIRED - ATOMICITY_UNAVAILABLE - VENUE_UNAVAILABLE - VENUE_NATIVE_RFQ_NO_RESPONSE - VENUE_NATIVE_RFQ_RESERVE_BREACH - VENUE_NATIVE_RFQ_SLIPPAGE_BREACH - VENUE_NATIVE_RFQ_FAILED - CLOB_NO_LIQUIDITY - CLOB_RESERVE_BREACH - CLOB_SLIPPAGE_BREACH - CLOB_FALLBACK_FAILED - MAPPING_INVALIDATED - COLLATERAL_INVALIDATED - PARTICIPANT_INELIGIBLE - SELF_TRADE_PREVENTED - UNAUTHORIZED_SIZE - SIGNER_UNAVAILABLE - MARKET_HALTED - VENUE_SESSION_LOST - MM_POPULATION_UNAVAILABLE - AUCTION_EXPIRED - TICK_PROFILE_STALE - VENUE_RULE_CHANGED - UNSUPPORTED_RAIL - INVALID_FALLBACK_POLICY - TOTAL_DEADLINE_EXCEEDED - INTERNAL_ERROR - BID_INVALID - INVALID_PRICE_RANGE - INVALID_PRICE_TICK - INVALID_QUANTITY_TICK - REVISION_CONFLICT - LATE_BID cancellation_reason_code: enum: - UNSPECIFIED - CLIENT_REQUEST - RISK_REDUCTION - MARKET_VIEW_CHANGED - ROUTING_CHANGE - DUPLICATE_ORDER - OTHER description: Originator-only durable cancellation instruction. cancellation_note: type: string maxLength: 240 description: Originator-only bounded operator audit note. reason_history: type: array items: $ref: '#/components/schemas/ReasonRecord' minimum_tranche_established: type: boolean allocation_calculation_version: type: string capacity_authority_status: enum: - PENDING_VENUE_RECONCILIATION - PENDING_PORTFOLIO_COVERAGE - PORTFOLIO_COVERAGE_CONFIRMED - AUTHORITY_EVIDENCE_UNAVAILABLE description: Fail-closed venue and portfolio-capacity reconciliation state. capacity_covered_by_source_sequence: type: string pattern: ^(0|[1-9][0-9]*)$ description: >- Originator-only sealed portfolio source sequence that explicitly covered every confirmed execution token. capacity_covered_at: type: string format: date-time description: >- Originator-only time at which explicit sealed coverage retired the capacity fence. capacity_portfolio_watermark: type: string maxLength: 256 description: >- Originator-only opaque portfolio revision certified by the covering snapshot. open_time: type: string format: date-time close_time: type: string format: date-time finalized_at: type: string format: date-time sequence: type: string pattern: ^(0|[1-9]\d*)$ description: Opaque auction authority sequence; compare as a decimal string. Quote: type: object required: - quote_id - auction_id - revision - price_atoms - max_executable_quantity_atoms - receive_sequence - received_at - status properties: quote_id: type: string format: uuid auction_id: type: string format: uuid revision: type: string pattern: ^(0|[1-9]\d*)$ description: Opaque unsigned quote revision; compare as a decimal string. price_atoms: $ref: '#/components/schemas/PriceAtoms' max_executable_quantity_atoms: type: integer format: int64 receive_sequence: type: string pattern: ^(0|[1-9]\d*)$ description: >- Participant-scoped durable acknowledgement sequence encoded as an opaque decimal string; private FIFO coordinates are never exposed. received_at: type: string format: date-time status: enum: - ACTIVE - WITHDRAWN - SUPERSEDED - FROZEN - SELECTED - INELIGIBLE Allocation: type: object required: - allocation_id - price_atoms - quantity_atoms - rail - venue - minimum_tranche - execution_status properties: allocation_id: type: string format: uuid participant_id: type: string description: >- Policy-authorized public counterparty selector when visible to this principal; never a hidden execution or venue-account identifier. price_atoms: $ref: '#/components/schemas/PriceAtoms' quantity_atoms: type: integer format: int64 rail: enum: - PRIVATE_BLOCK - VENUE_NATIVE_RFQ - CLOB venue: type: string minimum_tranche: type: boolean execution_status: enum: - PLANNED - SUBMITTED - CONFIRMED - REJECTED - UNKNOWN venue_execution_id: type: string confirmed_quantity_atoms: type: integer format: int64 confirmed_price_atoms: $ref: '#/components/schemas/PriceAtoms' expected_fee_atoms: type: string pattern: ^(0|-?[1-9][0-9]*)$ expected_all_in_value_atoms: type: string pattern: ^(0|-?[1-9][0-9]*)$ confirmed_fee_atoms: type: string pattern: ^(0|-?[1-9][0-9]*)$ confirmed_all_in_value_atoms: type: string pattern: ^(0|-?[1-9][0-9]*)$ rung_index: type: integer minimum: 0 submitted_at: type: string format: date-time acknowledged_at: type: string format: date-time finalized_at: type: string format: date-time PriceAtoms: type: integer format: int64 minimum: 0 maximum: 10000 description: One atom is 0.01 cent of probability-dollar price. FallbackRung: type: object required: - action properties: action: enum: - EXECUTE - CANCEL_REMAINDER default: EXECUTE rail: enum: - VENUE_NATIVE_RFQ - CLOB venue: type: string limit_price_atoms: $ref: '#/components/schemas/PriceAtoms' minimum_quantity_atoms: type: integer format: int64 minimum: 1 maximum_quantity_atoms: type: integer format: int64 minimum: 1 maximum_fraction_bps: type: integer format: int64 minimum: 1 maximum: 10000 default: 10000 timeout_ms: type: integer format: int64 minimum: 1 default: 2000 maximum_quote_age_ms: type: integer format: int64 minimum: 1 maximum: 5000 default: 500 allow_partial: type: boolean on_unavailable: enum: - CONTINUE - STOP default: CONTINUE on_reject: enum: - CONTINUE - STOP default: CONTINUE fee_profile: $ref: '#/components/schemas/FeeProfile' description: Server-pinned; caller values are not authoritative. route_rule_profile: $ref: '#/components/schemas/RouteRuleProfile' description: >- Server-pinned executable venue and mapping contract; caller values are not authoritative. RuleProfile: type: object description: >- Immutable venue, tick, atomicity, freshness, and fee-assumption snapshot pinned at admission. required: - version - venue - market_class - private_rail - price_tick_atoms - quantity_tick_atoms - minimum_block_atoms - minimum_leg_atoms - maximum_allocation_atoms - atomic_private_execution - public_benchmark_fee_scale_ppm - public_benchmark_max_age_ms - benchmark_calculation_version - valid_until properties: version: type: string venue: type: string market_class: type: string private_rail: enum: - PRIVATE_BLOCK - VENUE_NATIVE_RFQ - CLOB price_tick_atoms: type: integer format: int64 minimum: 1 quantity_tick_atoms: type: integer format: int64 minimum: 1 minimum_block_atoms: type: integer format: int64 minimum: 0 minimum_leg_atoms: type: integer format: int64 minimum: 0 maximum_allocation_atoms: type: integer format: int64 minimum: 1 atomic_private_execution: type: boolean private_fee_profile: $ref: '#/components/schemas/FeeProfile' public_benchmark_fee_scale_ppm: type: integer format: int64 minimum: 0 maximum: 1000000 public_benchmark_max_age_ms: type: integer format: int64 minimum: 1 maximum: 5000 benchmark_calculation_version: type: string minimum_scorecard_sample_count: type: integer minimum: 1 default: 10 maximum_scorecard_age_ms: type: integer format: int64 minimum: 1 valid_until: type: string format: date-time InvitationDelivery: type: object required: - requested_count - delivered_count - by_transport - participants properties: requested_count: type: integer minimum: 0 maximum: 16 delivered_count: type: integer minimum: 0 maximum: 16 by_transport: type: object additionalProperties: false required: - BROWSER - FIX properties: BROWSER: type: integer minimum: 0 maximum: 16 FIX: type: integer minimum: 0 maximum: 16 last_delivered_at: type: string format: date-time participants: type: array maxItems: 16 description: >- Originator-only delivery evidence keyed by public counterparty selector; hidden execution and delivery-session identities are never exposed. items: $ref: '#/components/schemas/InvitationParticipantDelivery' ReasonRecord: type: object required: - reason - stage - occurred_at - contributing properties: reason: type: string stage: type: string rung_index: type: integer minimum: 0 occurred_at: type: string format: date-time contributing: type: boolean FeeProfile: type: object required: - fee_profile_id - fee_profile_version - model - rate_ppm - fixed_fee_atoms - minimum_fee_atoms - prediction_fee_scale_ppm - rounding_mode - valid_until properties: fee_profile_id: type: string fee_profile_version: type: string model: enum: - NONE - NOTIONAL_PPM - PREDICTION_MARKET default: NONE rate_ppm: type: integer format: int64 minimum: -1000000 maximum: 1000000 fixed_fee_atoms: type: integer format: int64 minimum_fee_atoms: type: integer format: int64 minimum: 0 prediction_fee_scale_ppm: type: integer format: int64 minimum: -1000000 maximum: 1000000 rounding_mode: enum: - AGAINST_ORIGINATOR - NEAREST default: AGAINST_ORIGINATOR valid_until: type: string format: date-time RouteRuleProfile: type: object required: - version - venue - rail - mapping_version - venue_market_id - venue_outcome_id - route_id - price_tick_atoms - quantity_tick_atoms - minimum_order_atoms - maximum_order_atoms - atomic - self_trade_prevention_mode - control_group_version - valid_from - valid_until - mapping_valid_from - mapping_valid_until properties: version: type: string venue: type: string rail: enum: - VENUE_NATIVE_RFQ - CLOB mapping_version: type: string venue_market_id: type: string venue_outcome_id: type: string route_id: type: string price_tick_atoms: type: integer format: int64 minimum: 1 quantity_tick_atoms: type: integer format: int64 minimum: 1 minimum_order_atoms: type: integer format: int64 minimum: 1 maximum_order_atoms: type: integer format: int64 minimum: 1 atomic: type: boolean self_trade_prevention_mode: enum: - CONTROL_GROUP_REJECT control_group_version: type: string valid_from: type: string format: date-time valid_until: type: string format: date-time mapping_valid_from: type: string format: date-time mapping_valid_until: type: string format: date-time InvitationParticipantDelivery: type: object required: - participant_id - delivered properties: participant_id: type: string maxLength: 128 description: Public counterparty selector frozen for this auction. delivered: type: boolean transport: enum: - BROWSER - FIX delivered_at: type: string format: date-time responses: InvalidAuctionID: description: >- `invalid_auction_id` — the path identifier is not a canonical UUID carrying a valid owner shard. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_auction_id Unauthorized: description: | The bearer session is absent, malformed, expired, revoked, signed by an unrecognized key, carries the wrong issuer, audience, or schema version, or its subject is not enrolled in the Auction House. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: authentication required InternalRoutingHeaders: description: >- `internal_routing_headers_forbidden` — the request carried `X-Service-Token`, `X-Agora-Peer`, `X-Agora-Active-Only`, or `X-Agora-Owner-Read-Fallback`. These are internal owner-routing capabilities, not public API options. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal_routing_headers_forbidden securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.