> ## 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 the caller's complete role-filtered audit timeline > Reads the existing owner journal for a live auction or the existing shared kairos_execution projection for completed history. Completeness is verified before returning. Raw authority sequence numbers, event IDs, owner/session identifiers, hidden execution identities, and every competing-maker quote event are omitted so gaps cannot disclose private participation. ## OpenAPI ````yaml /openapi/agora.yaml get /v1/auctions/{auctionID}/events 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}/events: parameters: - $ref: '#/components/parameters/AuctionID' get: summary: Get the caller's complete role-filtered audit timeline description: | Reads the existing owner journal for a live auction or the existing shared kairos_execution projection for completed history. Completeness is verified before returning. Raw authority sequence numbers, event IDs, owner/session identifiers, hidden execution identities, and every competing-maker quote event are omitted so gaps cannot disclose private participation. responses: '200': description: Complete ordered timeline visible to this principal headers: Cache-Control: schema: type: string example: private, no-store content: application/json: schema: $ref: '#/components/schemas/AuctionAuditTimeline' '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 '500': description: >- `internal_error` — the projected history was readable but not contiguous through its authoritative snapshot, so no partial timeline is returned. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: | The complete owner journal or shared audit projection cannot currently be verified: `audit_history_unavailable` (owner journal scan failed) or `audit_projection_unavailable` (no audit reader, or the shared projection backlog is unsafe). 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: AuctionAuditTimeline: type: object required: - auction_id - as_of - complete - events properties: auction_id: type: string format: uuid as_of: type: string format: date-time complete: type: boolean enum: - true description: >- True only after the selected durable history is verified contiguous through its authoritative snapshot. events: type: array maxItems: 4096 description: >- Ordered caller-visible events. Hidden events do not leave sequence gaps because raw authority coordinates are never exposed. items: $ref: '#/components/schemas/AuctionAuditEvent' 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. AuctionAuditEvent: type: object required: - type - occurred_at properties: type: type: string occurred_at: type: string format: date-time state_before: type: string state_after: type: string reason: type: string actor_scope: enum: - SYSTEM - YOU - COUNTERPARTY quote_revision: type: string pattern: ^(0|[1-9]\d*)$ description: Caller-owned quote revision only. quote_price_atoms: $ref: '#/components/schemas/PriceAtoms' quote_quantity_atoms: type: integer format: int64 minimum: 1 description: Caller-owned quote quantity only. cancellation_reason_code: enum: - UNSPECIFIED - CLIENT_REQUEST - RISK_REDUCTION - MARKET_VIEW_CHANGED - ROUTING_CHANGE - DUPLICATE_ORDER - OTHER description: >- Originator-only durable cancellation instruction; never returned to invitees. operator_note: type: string maxLength: 240 description: Originator-only cancellation note. PriceAtoms: type: integer format: int64 minimum: 0 maximum: 10000 description: One atom is 0.01 cent of probability-dollar price. 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.