get:
  operationId: "getHeader"
  summary: Get an execution payload header.
  description: |
    Requests a builder node to produce a valid execution payload header, which
    can be integrated into a blinded beacon block and signed.

    If the builder is unable to produce a valid execution payload header, then
    the builder MUST return a 204 response. If the request is invalid, then the
    builder MUST return an error response (400) with a description of the
    validation failure.

    After Deneb, return the KZG commitments for any associated blobs attached to the execution payload.
  tags:
    - Builder
  parameters:
    - name: slot
      in: path
      required: true
      description: The slot for which the block should be proposed.
      schema:
        $ref: "../../builder-oapi.yaml#/components/schemas/Uint64"
    - name: parent_hash
      in: path
      required: true
      description: Hash of execution layer block the proposer will build on.
      schema:
        $ref: "../../builder-oapi.yaml#/components/schemas/Root"
    - name: pubkey
      in: path
      required: true
      description: The validator's BLS public key.
      schema:
        $ref: "../../builder-oapi.yaml#/components/schemas/Pubkey"
    - name: Date-Milliseconds
      in: header
      required: false
      description: |
        Optional header containing a Unix timestamp in milliseconds representing
        the point-in-time the request was sent. This header can be used to measure
        latency.
      schema:
        type: integer
        format: int64
        example: 1710338135000
    - name: X-Timeout-Ms
      in: header
      required: false
      description: |
        Optional header containing the proposer's timeout for the request in milliseconds. 
        Relays should use this header to adjust the amount of time by which they delay getHeader 
        requests to maximise block rewards. Otherwise, getHeader requests will timeout and the proposer 
        will not receive the header in time.
      schema:
        type: integer
        format: int64
        example: 10000
  responses:
    "200":
      description: Success response.
      headers:
        Eth-Consensus-Version:
          $ref: "../../builder-oapi.yaml#/components/headers/Eth-Consensus-Version"
          required: false
      content:
        application/json:
          schema:
            title: GetHeaderResponse
            type: object
            required: [version, data]
            properties:
              version:
                type: string
                enum: [ bellatrix, capella, deneb, electra, fulu ]
                example: "bellatrix"
              data:
                anyOf:
                 - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBuilderBid"
                 - $ref: "../../builder-oapi.yaml#/components/schemas/Capella.SignedBuilderBid"
                 - $ref: "../../builder-oapi.yaml#/components/schemas/Deneb.SignedBuilderBid"
                 - $ref: "../../builder-oapi.yaml#/components/schemas/Electra.SignedBuilderBid"
          examples:
            bellatrix:
              $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBuilderBid"
            capella:
              $ref: "../../builder-oapi.yaml#/components/examples/Capella.SignedBuilderBid"
            deneb:
              $ref: "../../builder-oapi.yaml#/components/examples/Deneb.SignedBuilderBid"
            electra:
              $ref: "../../builder-oapi.yaml#/components/examples/Electra.SignedBuilderBid"
            fulu:
              $ref: "../../builder-oapi.yaml#/components/examples/Fulu.SignedBuilderBid"
        application/octet-stream:
          schema:
            description: "SSZ serialized `SignedBuilderBid` bytes. Use Accept header to choose this response type"
    "204":
      description: No header is available.
    "400":
      description: Error response.
      content:
        application/json:
          schema:
            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
          examples:
            InvalidRequest:
              value:
                code: 400
                message: "Unknown hash: missing parent hash"
    "406":
      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
    "500":
      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"