openapi: 3.1.0
info:
  title: ZERO Public Operator API
  version: 1.0.0
  description: Read-only public contracts for verified ZERO operator behavior. JSON Schemas are published at /contracts/zero.public_operators.v1.schema.json and /contracts/zero.public_operator.v1.schema.json.
externalDocs:
  description: Public operator contract guide and JSON Schema artifacts.
  url: https://getzero.dev/contracts/public-operator.md
x-json-schemas:
  public_operator_index: https://getzero.dev/contracts/zero.public_operators.v1.schema.json
  public_operator_profile: https://getzero.dev/contracts/zero.public_operator.v1.schema.json
servers:
  - url: https://getzero.dev
paths:
  /api/public/operators:
    get:
      operationId: listPublicOperators
      summary: List public ZERO operators.
      security: []
      responses:
        "200":
          description: Public operator index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicOperatorIndex"
  /api/public/operators/{name}:
    get:
      operationId: getPublicOperator
      summary: Get a normalized public operator profile.
      security: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            enum: [foundation]
      responses:
        "200":
          description: Public operator profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicOperatorProfile"
        "404":
          description: Public operator not found.
  /api/arena:
    get:
      operationId: getArena
      summary: Get current arena leaderboard.
      security: []
      responses:
        "200":
          description: Arena leaderboard, public operator sourced when available.
  /api/arena/rewards:
    get:
      operationId: getArenaRewards
      summary: Get current weekly proof rewards.
      security: []
      responses:
        "200":
          description: Weekly rewards payload.
  /api/seasons:
    get:
      operationId: getSeason
      summary: Get current proof-based season state.
      security: []
      responses:
        "200":
          description: Season leaderboard payload.
components:
  schemas:
    PublicOperatorIndex:
      type: object
      required: [schema_version, kind, count, operators]
      properties:
        schema_version:
          const: zero.public_operators.v1
        kind:
          const: operator_profile_index
        count:
          type: integer
          minimum: 0
        operators:
          type: array
          items:
            $ref: "#/components/schemas/PublicOperatorSummary"
    PublicOperatorSummary:
      type: object
      required:
        - handle
        - canonical_url
        - public_operator_url
        - raw_evidence_url
        - mode
        - signed_receipts
        - total_receipts
        - private_keys_stored
        - evidence_schema
      properties:
        handle:
          type: string
        display_name:
          type: string
        tier:
          type: string
        canonical_url:
          type: string
          format: uri
        public_operator_url:
          type: string
          format: uri
        raw_evidence_url:
          type: string
          format: uri
        score_label:
          type: string
        mode:
          type: string
          enum: [paper, live]
        runtime_state:
          type: string
        venue:
          type: string
        custody_model:
          type: string
        signing_boundary:
          type: string
        signed_receipts:
          type: integer
          minimum: 0
        total_receipts:
          type: integer
          minimum: 0
        private_keys_stored:
          type: boolean
        evidence_schema:
          const: zero.public_operator.v1
    PublicOperatorProfile:
      type: object
      required:
        - schema_version
        - kind
        - handle
        - canonical_url
        - raw_evidence_url
        - visibility
        - profile
        - score
        - capabilities
        - agents
        - evidence
        - verification
      properties:
        schema_version:
          const: zero.public_operator.v1
        kind:
          const: operator_profile
        handle:
          type: string
        canonical_url:
          type: string
          format: uri
        raw_evidence_url:
          type: string
          format: uri
        visibility:
          const: public
        profile:
          type: object
        score:
          type: object
        capabilities:
          type: object
          required: [operating_system, venue, mode, custody_model, signing_boundary, allowed_actions]
          properties:
            operating_system:
              const: zero
            venue:
              type: string
            mode:
              type: string
              enum: [paper, live]
            custody_model:
              type: string
            signing_boundary:
              type: string
            allowed_actions:
              type: array
              items:
                type: string
                enum: [order, cancel, scheduleCancel]
        agents:
          type: array
        evidence:
          type: object
          required: [source, deployment_id, signed_receipts, total_receipts, open_positions]
          properties:
            source:
              const: foundation
            deployment_id:
              type: string
            signed_receipts:
              type: integer
              minimum: 0
            total_receipts:
              type: integer
              minimum: 0
            open_positions:
              type: integer
              minimum: 0
        verification:
          type: object
          required: [private_keys_stored, server_signing, public_wallets]
          properties:
            private_keys_stored:
              type: boolean
            server_signing:
              type: string
            public_wallets:
              type: object