openapi: 3.1.0
info:
  title: Celestia Node Header API
  version: 0.30.x
  description: |
    JSON-RPC methods in the `header` module of celestia-node. Provides access to
    Celestia extended block headers, sync state, and header subscription. Used by
    light clients, rollups, and indexers to track the canonical Celestia chain head
    and verify data availability commitments per height.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:26658
    description: Default celestia-node JSON-RPC endpoint
tags:
  - name: Header
    description: Query and subscribe to Celestia extended block headers.
paths:
  /:
    post:
      tags: [Header]
      summary: Invoke Header JSON-RPC Method
      description: |
        Single JSON-RPC entrypoint exposing the `header.*` namespace including
        `header.LocalHead`, `header.NetworkHead`, `header.GetByHeight`,
        `header.GetByHash`, `header.GetRangeByHeight`, `header.SyncState`,
        `header.SyncWait`, `header.WaitForHeight`, and `header.Subscribe`.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              localHead:
                summary: Get local head
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: header.LocalHead
                  params: []
              getByHeight:
                summary: Get header by height
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: header.GetByHeight
                  params: [1234567]
      responses:
        '200':
          description: JSON-RPC response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method, id]
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          oneOf: [{type: integer}, {type: string}]
        method:
          type: string
          enum:
            - header.LocalHead
            - header.NetworkHead
            - header.GetByHeight
            - header.GetByHash
            - header.GetRangeByHeight
            - header.SyncState
            - header.SyncWait
            - header.WaitForHeight
            - header.Subscribe
        params:
          type: array
    JsonRpcResponse:
      type: object
      properties:
        jsonrpc: {type: string}
        id: {}
        result: {}
        error:
          type: object
          properties:
            code: {type: integer}
            message: {type: string}
    ExtendedHeader:
      type: object
      properties:
        header:
          type: object
          description: Tendermint/CometBFT block header.
          properties:
            height: {type: integer}
            time: {type: string, format: date-time}
            chain_id: {type: string}
            data_hash: {type: string}
        commit:
          type: object
        validator_set:
          type: object
        dah:
          type: object
          description: Data Availability Header (row/column roots over the EDS).
          properties:
            row_roots:
              type: array
              items: {type: string}
            column_roots:
              type: array
              items: {type: string}