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

# Owner readiness

> Reports whether this owner accepts new work. Fails closed while
draining, while the local authority journal is unavailable, and when
the shared Kairos control schema cannot be reached.




## OpenAPI

````yaml /openapi/agora.yaml get /readyz
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 <jwt>`, 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.<base64url(jwt)>`.

    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": "<code>"}`, 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:
  /readyz:
    get:
      summary: Owner readiness
      description: |
        Reports whether this owner accepts new work. Fails closed while
        draining, while the local authority journal is unavailable, and when
        the shared Kairos control schema cannot be reached.
      responses:
        '200':
          description: Ready for new work
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                status: ready
        '503':
          description: >-
            Draining, local authority journal unavailable, or shared Kairos
            control schema unavailable. `status` names the failing condition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      security: []
components:
  schemas:
    Status:
      type: object
      required:
        - status
      properties:
        status:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.