> ## 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. # Read the authenticated participant's durable private invitation inbox > Returns only unexpired invitations published to the caller's account before the common close time. ## OpenAPI ````yaml /openapi/agora.yaml get /v1/invitations 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/invitations: get: summary: Read the authenticated participant's durable private invitation inbox description: >- Returns only unexpired invitations published to the caller's account before the common close time. responses: '200': description: Unexpired private invitation envelopes content: application/json: schema: type: object required: - invitations properties: invitations: type: array items: $ref: '#/components/schemas/InvitationInboxItem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InternalRoutingHeaders' '503': description: >- `invitation_inbox_unavailable` — the inbox is not configured on this deployment or its durable read failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invitation_inbox_unavailable components: schemas: InvitationInboxItem: type: object required: - auction_id - invitation - close_time - published_at properties: auction_id: type: string format: uuid invitation: $ref: '#/components/schemas/InvitationPayload' close_time: type: string format: date-time published_at: type: string format: date-time 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. InvitationPayload: type: object required: - auction_id - market_id - outcome_id - side - fill_instruction - min_fill_quantity_atoms - max_fill_quantity_atoms - execution_objective_quantity_atoms - objective_mode - close_time - venue_scope - customer_class - allocation_policy - price_tick_atoms - quantity_tick_atoms - minimum_leg_atoms - maximum_mm_concentration_bps - private_fee_profile properties: auction_id: type: string format: uuid 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 execution_objective_quantity_atoms: type: integer format: int64 objective_mode: enum: - STOP_AT_TARGET - SEEK_MAXIMUM close_time: type: string format: date-time venue_scope: type: array items: type: string customer_class: type: string allocation_policy: enum: - PRICE_FIRST - COMPLETION_FIRST price_tick_atoms: type: integer format: int64 quantity_tick_atoms: type: integer format: int64 minimum_leg_atoms: type: integer format: int64 maximum_mm_concentration_bps: type: integer format: int64 private_fee_profile: $ref: '#/components/schemas/FeeProfile' originator_identity: type: string description: >- Present only when the auction's identity policy is REVEAL_TO_INVITEES. 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 responses: 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.