openapi: 3.0.3
info:
  title: Flare Data Availability Client API
  version: 1.0.0
  description: |
    OpenAPI specification for Data Availability Client API. 
    The public API endpoints are rate limited, to request an API key for higher limits, create an [API Key Request Issue](https://github.com/flare-foundation/developer-hub/issues/new/choose).
servers:
  - url: "https://flr-data-availability.flare.network/"
  - url: "https://ctn2-data-availability.flare.network/"
  - url: "https://sgb-data-availability.flare.network/"
  - url: "https://ctn-data-availability.flare.network/"
paths:
  /api/health:
    get:
      operationId: api_health_retrieve
      description: Checks whether the data availability runs correctly
      tags:
        - api
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
          description: ""
  /api/v0/fsp/latest-voting-round:
    get:
      operationId: fsp_latest_voting_round_retrieve
      description: Retrieves the last voting round id and its starting timestamp
      tags:
        - fsp
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VotingRound"
          description: ""
  /api/v0/fsp/status:
    get:
      operationId: fsp_status_retrieve
      description:
        Retrieves the last voting round id and its starting timestamp for
        fdc and ftso
      tags:
        - fsp
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VotingRoundStatus"
          description: ""
  /api/v0/ftso/anchor-feed-names:
    get:
      operationId: ftso_anchor_feed_names_list
      description: Retrieves the feed id and feed name based on voting round id
      parameters:
        - in: query
          name: voting_round_id
          schema:
            type: integer
          description: Voting round. Defaults to latest.
      tags:
        - ftso
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FeedValueName"
          description: ""
  /api/v0/ftso/anchor-feeds-with-proof:
    post:
      operationId: ftso_anchor_feeds_with_proof_create
      description:
        Retrieves the feed values with there proofs based on voting round
        id and feed ids
      parameters:
        - in: query
          name: voting_round_id
          schema:
            type: integer
          description: Voting round. Defaults to latest.
      tags:
        - ftso
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedResultFeedsWithProofsRequestRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/FeedResultFeedsWithProofsRequestRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/FeedResultFeedsWithProofsRequestRequest"
        required: true
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MerkleProofValue"
          description: ""
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationTypeGetByRoundIdBytesError"
          description: Bad request — invalid feed ids or voting round
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
          description: Unauthorized — invalid API key
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
          description: Rate limited — request an API key for higher limits
  /api/v1/fdc:
    get:
      operationId: fdc_list_2
      description:
        Returns full merkle tree with proof for each leaf for given round.
        Leaves are ABI decoded.
      parameters:
        - in: query
          name: voting_round_id
          schema:
            type: integer
          description: Voting round.
          required: true
      tags:
        - fdc
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AttestationResultV1"
          description: ""
  /api/v1/fdc/proof-by-request-round:
    post:
      operationId: fdc_proof_by_request_round_create
      description:
        Retrieves the attestation request proof for given request bytes
        and voting round. Leaves are ABI decoded.
      tags:
        - fdc
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
        required: true
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationResultV1"
          description: ""
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationTypeGetByRoundIdBytesError"
          description: ""
  /api/v1/fdc/proof-by-request-round-raw:
    post:
      operationId: fdc_proof_by_request_round_raw_create
      description:
        Retrieves the attestation request proof for given request bytes
        and voting round. Leaves are ABI encoded.
      tags:
        - fdc
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/AttestationResponseProofByRequestRoundV1RequestRequest"
        required: true
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationResultRawV1"
          description: ""
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationTypeGetByRoundIdBytesError"
          description: ""
  /api/v1/fdc/raw:
    get:
      operationId: fdc_raw_list
      description:
        Returns full merkle tree with proof for each leaf for given round.
        Leaves are ABI encoded.
      parameters:
        - in: query
          name: voting_round_id
          schema:
            type: integer
          description: Voting round.
          required: true
      tags:
        - fdc
      security:
        - ApiKeyAuth: []
        - {}
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AttestationResultRawV1"
          description: ""
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Optional API key for higher rate limits.
        Provide via the `X-API-Key` header. Without a key, public rate limits apply.
        Request a key via the Developer Hub API Key Request issue template.

  schemas:
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Optional machine-readable error code
        hint:
          type: string
          description: Optional resolution hint for clients and agents
    AttestationResponseProofByRequestRoundV1RequestRequest:
      type: object
      properties:
        votingRoundId:
          type: integer
          description:
            Specific voting round from which the proof should be fetched.
            If not provided latest matching proof will be fetched instead.
        requestBytes:
          type: string
          minLength: 1
          description: Hex encoded attestation request.
      required:
        - requestBytes
    AttestationResultRawV1:
      type: object
      properties:
        response_hex:
          type: string
          readOnly: true
        attestation_type:
          type: string
          readOnly: true
        proof:
          type: array
          items:
            type: string
      required:
        - attestation_type
        - proof
        - response_hex
    AttestationResultV0:
      type: object
      properties:
        response:
          type: object
          additionalProperties: {}
        proof:
          type: array
          items:
            type: string
      required:
        - proof
        - response
    AttestationResultV1:
      type: object
      properties:
        response:
          type: object
          additionalProperties: {}
        proof:
          type: array
          items:
            type: string
      required:
        - proof
        - response
    AttestationTypeGetByRoundBytesError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    AttestationTypeGetByRoundBytesV0RequestRequest:
      type: object
      properties:
        requestBytes:
          type: string
          minLength: 1
          description: Request bytes that were send (emitted)
      required:
        - requestBytes
    AttestationTypeGetByRoundIdBytesError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    AttestationTypeGetByRoundIdBytesv0RequestRequest:
      type: object
      properties:
        votingRoundId:
          type: integer
          description: Voting round when the request was made
        requestBytes:
          type: string
          minLength: 1
          description: Request bytes that were send (emitted)
      required:
        - requestBytes
        - votingRoundId
    FeedResultFeedsWithProofsRequestRequest:
      type: object
      properties:
        feed_ids:
          type: array
          items:
            type: string
            minLength: 1
          description: List of feed ids with 0x prefixes included
      required:
        - feed_ids
    FeedValueName:
      type: object
      properties:
        feed_id:
          type: string
        feed_name:
          type: string
      required:
        - feed_id
        - feed_name
    FeedValueStruct:
      type: object
      description:
        Serializer that returns the feed in a json format that matches
        ABI definition
      properties:
        votingRoundId:
          type: integer
        id:
          type: string
        value:
          type: integer
        turnoutBIPS:
          type: integer
        decimals:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
      required:
        - decimals
        - id
        - turnoutBIPS
        - value
        - votingRoundId
    Health:
      type: object
      properties:
        healthy:
          type: boolean
      required:
        - healthy
    MerkleProofValue:
      type: object
      properties:
        body:
          $ref: "#/components/schemas/FeedValueStruct"
        proof:
          type: array
          items:
            type: string
      required:
        - body
        - proof
    VotingRound:
      type: object
      properties:
        voting_round_id:
          type: integer
        start_timestamp:
          type: integer
      required:
        - start_timestamp
        - voting_round_id
    VotingRoundStatus:
      type: object
      properties:
        active:
          $ref: "#/components/schemas/VotingRound"
        latest_fdc:
          $ref: "#/components/schemas/VotingRound"
        latest_ftso:
          $ref: "#/components/schemas/VotingRound"
      required:
        - active
        - latest_fdc
        - latest_ftso