Symbiotic SymbioticAPIService API

openapi: 3.2.0
info:
  title: v1/api.proto Symbiotic API Service API
  version: version not set
tags:
- name: SymbioticAPIService
paths:
  /v1/aggregation/proof/{requestId}:
    get:
      summary: Get aggregation proof
      operationId: SymbioticAPIService_GetAggregationProof
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAggregationProofResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/aggregation/proofs/epoch/{epoch}:
    get:
      summary: Get aggregation proofs by epoch
      operationId: SymbioticAPIService_GetAggregationProofsByEpoch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAggregationProofsByEpochResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number
        in: path
        required: true
        schema:
          type: string
          format: uint64
      - name: pageSize
        description: Maximum number of items to return. 0 = server default (100). Server clamps to max (1000).
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: from
        description: Opaque pagination cursor from a previous response's `next_from`. Empty string starts from the beginning.
        in: query
        required: false
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/aggregation/status/{requestId}:
    get:
      summary: Get aggregation status, can be sent only to aggregator nodes
      operationId: SymbioticAPIService_GetAggregationStatus
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAggregationStatusResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/committed/all:
    get:
      summary: Get last committed epochs for all settlement chains
      operationId: SymbioticAPIService_GetLastAllCommitted
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLastAllCommittedResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - SymbioticAPIService
  /v1/committed/chain/{settlementChainId}:
    get:
      summary: Get last committed epoch for a specific settlement chain
      operationId: SymbioticAPIService_GetLastCommitted
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLastCommittedResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: settlementChainId
        description: Settlement chain ID
        in: path
        required: true
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/epoch/current:
    get:
      summary: Get current epoch
      operationId: SymbioticAPIService_GetCurrentEpoch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCurrentEpochResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - SymbioticAPIService
  /v1/sign:
    post:
      summary: Sign a message
      operationId: SymbioticAPIService_SignMessage
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignMessageResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - SymbioticAPIService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignMessageRequest'
        required: true
  /v1/signature-request-ids/epoch/{epoch}:
    get:
      summary: Get all signature request IDs by epoch
      operationId: SymbioticAPIService_GetSignatureRequestIDsByEpoch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignatureRequestIDsByEpochResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number
        in: path
        required: true
        schema:
          type: string
          format: uint64
      - name: pageSize
        description: Maximum number of items to return. 0 = server default (1000). Server clamps to max (10000).
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: from
        description: Opaque pagination cursor from a previous response's `next_from`. Empty string starts from the beginning.
        in: query
        required: false
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/signature-request/{requestId}:
    get:
      summary: Get signature request by request id
      operationId: SymbioticAPIService_GetSignatureRequest
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignatureRequestResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/signature-requests/epoch/{epoch}:
    get:
      summary: Get all signature requests by epoch
      operationId: SymbioticAPIService_GetSignatureRequestsByEpoch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignatureRequestsByEpochResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number
        in: path
        required: true
        schema:
          type: string
          format: uint64
      - name: pageSize
        description: Maximum number of items to return. 0 = server default (100). Server clamps to max (1000).
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: from
        description: Opaque pagination cursor from a previous response's `next_from`. Empty string starts from the beginning.
        in: query
        required: false
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/signatures/epoch/{epoch}:
    get:
      summary: Get signature by epoch
      operationId: SymbioticAPIService_GetSignaturesByEpoch
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignaturesByEpochResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number
        in: path
        required: true
        schema:
          type: string
          format: uint64
      - name: pageSize
        description: Maximum number of items to return. 0 = server default (100). Server clamps to max (1000).
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: from
        description: Opaque pagination cursor from a previous response's `next_from`. Empty string starts from the beginning.
        in: query
        required: false
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/signatures/{requestId}:
    get:
      summary: Get signature by request id
      operationId: SymbioticAPIService_GetSignatures
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignaturesResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      tags:
      - SymbioticAPIService
  /v1/stream/proofs:
    get:
      summary: Stream aggregation proofs in real-time. If start_epoch is provided, sends historical data first
      operationId: SymbioticAPIService_ListenProofs
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ListenProofsResponse'
                  error:
                    $ref: '#/components/schemas/Status'
                title: Stream result of ListenProofsResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: startEpoch
        description: 'Optional: start epoch. If provided, stream will first send all historical proofs starting from this epoch, then continue with real-time updates

          If not provided, only proofs generated after stream creation will be sent'
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/stream/signatures:
    get:
      summary: Stream signatures in real-time. If start_epoch is provided, sends historical data first
      operationId: SymbioticAPIService_ListenSignatures
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ListenSignaturesResponse'
                  error:
                    $ref: '#/components/schemas/Status'
                title: Stream result of ListenSignaturesResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: startEpoch
        description: 'Optional: start epoch. If provided, stream will first send all historical signatures starting from this epoch, then continue with real-time updates

          If not provided, only signatures generated after stream creation will be sent'
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/stream/validator-set:
    get:
      summary: Stream validator set changes in real-time. If start_epoch is provided, sends historical data first
      operationId: SymbioticAPIService_ListenValidatorSet
      responses:
        '200':
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ListenValidatorSetResponse'
                  error:
                    $ref: '#/components/schemas/Status'
                title: Stream result of ListenValidatorSetResponse
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: startEpoch
        description: 'Optional: start epoch. If provided, stream will first send all historical validator sets starting from this epoch, then continue with real-time updates

          If not provided, only validator sets generated after stream creation will be sent'
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator-set:
    get:
      summary: Get current validator set
      operationId: SymbioticAPIService_GetValidatorSet
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidatorSetResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator-set/custom-schedule/node-status:
    get:
      summary: 'Checks if the current node should be active based on a custom schedule derived from the validator set.

        This enables external applications to use the relay''s validator set for coordinating distributed tasks,

        such as deciding which application instances should commit data on-chain or perform other coordinated actions.

        The schedule ensures deterministic but randomized selection of active nodes at any given time.'
      operationId: SymbioticAPIService_GetCustomScheduleNodeStatus
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomScheduleNodeStatusResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number to use for the validator set (optional, defaults to current epoch)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      - name: seed
        description: 'Custom seed for randomizing the schedule (optional). Different seeds produce different schedules

          for the same epoch, allowing multiple independent scheduling schemes. If not provided, the schedule

          is deterministic based on epoch alone.'
        in: query
        required: false
        schema:
          type: string
          format: byte
      - name: slotDurationSeconds
        description: 'Duration of each time slot in seconds. Determines how frequently active groups rotate.

          Example: 60 seconds means a new group becomes active every minute.'
        in: query
        required: false
        schema:
          type: string
          format: uint64
      - name: maxParticipantsPerSlot
        description: 'Maximum validators per group. Controls redundancy: 1 for single-instance actions (less redundancy),

          2+ for multi-instance actions (more reliability). All validators in a group are active simultaneously.'
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: minParticipantsPerSlot
        description: 'Minimum validators required to form a remainder group. When dividing validators into groups,

          any remainder smaller than this is not scheduled. Set equal to max for strict group sizes.'
        in: query
        required: false
        schema:
          type: integer
          format: int64
      tags:
      - SymbioticAPIService
  /v1/validator-set/header:
    get:
      summary: Get validator set header
      operationId: SymbioticAPIService_GetValidatorSetHeader
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidatorSetHeaderResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator-set/metadata:
    get:
      summary: Get validator set metadata like extra data and request id to fetch aggregation and signature requests
      operationId: SymbioticAPIService_GetValidatorSetMetadata
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidatorSetMetadataResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator/address/{address}:
    get:
      summary: Get validator by address
      operationId: SymbioticAPIService_GetValidatorByAddress
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidatorByAddressResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: address
        description: Validator address (required)
        in: path
        required: true
        schema:
          type: string
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator/key/{keyTag}/{onChainKey}:
    get:
      summary: Get validator by key
      operationId: SymbioticAPIService_GetValidatorByKey
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidatorByKeyResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: keyTag
        description: Validator key tag (required)
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: onChainKey
        description: Validator on chain (public) key (required)
        in: path
        required: true
        schema:
          type: string
          format: byte
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
  /v1/validator/local:
    get:
      summary: Get local validator
      operationId: SymbioticAPIService_GetLocalValidator
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLocalValidatorResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      parameters:
      - name: epoch
        description: Epoch number (optional, if not provided current epoch will be used)
        in: query
        required: false
        schema:
          type: string
          format: uint64
      tags:
      - SymbioticAPIService
components:
  schemas:
    GetCustomScheduleNodeStatusResponse:
      type: object
      properties:
        isActive:
          type: boolean
          description: 'True if this node is active in the current time slot and should perform the scheduled action.

            False if this node should wait (another group is active). When multiple validators share a slot,

            all return true simultaneously, enabling coordinated redundancy.'
        currentSlotStartTime:
          type: string
          format: date-time
          description: 'Start time of the current active slot. This marks the beginning of the current slot time window.

            Can be used to determine how much time is left in the slot.'
        currentSlotEndTime:
          type: string
          format: date-time
          description: 'End time of the current active slot. This marks the end of the current slot time window.

            Can be used to determine how much time is left in the slot.'
      description: Response indicating whether the current node should be active now.
    ListenSignaturesResponse:
      type: object
      properties:
        requestId:
          type: string
          title: Id of the signature request
        epoch:
          type: string
          format: uint64
          title: Epoch number
        signature:
          $ref: '#/components/schemas/Signature'
          title: Signature data
      title: Response message for signatures stream
    GetValidatorSetResponse:
      type: object
      properties:
        validatorSet:
          $ref: '#/components/schemas/ValidatorSet'
          title: The validator set
      title: Response message for getting validator set
    GetValidatorSetMetadataResponse:
      type: object
      properties:
        extraData:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/ExtraData'
        commitmentData:
          type: string
          format: byte
        requestId:
          type: string
      title: Response message for getting validator set header
    GetSignatureRequestIDsByEpochResponse:
      type: object
      properties:
        requestIds:
          type: array
          items:
            type: string
          title: List of all signature request IDs for the epoch
        nextFrom:
          type: string
          description: Cursor to retrieve the next page. Empty when this is the last page.
      title: Response message for getting all signature request IDs by epoch
    Any:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    GetAggregationStatusResponse:
      type: object
      properties:
        currentVotingPower:
          type: string
          title: Current voting power of the aggregator (big integer as string)
        signerOperators:
          type: array
          items:
            type: string
          title: List of operator addresses that signed the request
      title: Response message for getting aggregation status
    ValidatorSetStatus:
      type: string
      enum:
      - VALIDATOR_SET_STATUS_UNSPECIFIED
      - VALIDATOR_SET_STATUS_DERIVED
      - VALIDATOR_SET_STATUS_AGGREGATED
      - VALIDATOR_SET_STATUS_COMMITTED
      default: VALIDATOR_SET_STATUS_UNSPECIFIED
      description: "- VALIDATOR_SET_STATUS_UNSPECIFIED: Default/unknown status\n - VALIDATOR_SET_STATUS_DERIVED: Derived status\n - VALIDATOR_SET_STATUS_AGGREGATED: Aggregated status\n - VALIDATOR_SET_STATUS_COMMITTED: Committed status"
      title: Validator set status enumeration
    GetValidatorByAddressResponse:
      type: object
      properties:
        validator:
          $ref: '#/components/schemas/Validator'
          title: The validator
      title: Response message for getting validator by address
    ListenValidatorSetResponse:
      type: object
      properties:
        validatorSet:
          $ref: '#/components/schemas/ValidatorSet'
          title: The validator set
      title: Response message for validator set changes stream
    AggregationProof:
      type: object
      properties:
        messageHash:
          type: string
          format: byte
          title: Message hash
        proof:
          type: string
          format: byte
          title: Proof data
        requestId:
          type: string
          title: Request ID
      title: Response message for getting aggregation proof
    GetSignatureRequestsByEpochResponse:
      type: object
      properties:
        signatureRequests:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/SignatureRequest'
          title: List of all signature requests for the epoch
        nextFrom:
          type: string
          description: Cursor to retrieve the next page. Empty when this is the last page.
      title: Response message for getting all signature requests by epoch
    GetSignaturesResponse:
      type: object
      properties:
        signatures:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Signature'
          title: List of signatures
      title: Response message for getting signatures
    GetAggregationProofResponse:
      type: object
      properties:
        aggregationProof:
          $ref: '#/components/schemas/AggregationProof'
      title: Response message for getting aggregation proof
    GetLastAllCommittedResponse:
      type: object
      properties:
        epochInfos:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ChainEpochInfo'
          title: List of settlement chains with their last committed epochs
        suggestedEpochInfo:
          $ref: '#/components/schemas/ChainEpochInfo'
          title: Suggested epoch info for signatures, it is the minimum commited epoch among all chains
      title: Response message for getting all last committed epochs
    GetValidatorSetHeaderResponse:
      type: object
      properties:
        version:
          type: integer
          format: int64
          title: Version of the validator set
        requiredKeyTag:
          type: integer
          format: int64
          title: Key tag required to commit next validator set
        epoch:
          type: string
          format: uint64
          title: Validator set epoch
        captureTimestamp:
          type: string
          format: date-time
          title: Epoch capture timestamp
        quorumThreshold:
          type: string
          title: Quorum threshold (big integer as string)
        totalVotingPower:
          type: string
          title: Total voting power (big integer as string)
        validatorsSszMroot:
          type: string
          title: Validators SSZ Merkle root (hex string)
      title: Response message for getting validator set header
    GetValidatorByKeyResponse:
      type: object
      properties:
        validator:
          $ref: '#/components/schemas/Validator'
          title: The validator
      title: Response message for getting validator by key
    GetLastCommittedResponse:
      type: object
      properties:
        settlementChainId:
          type: string
          format: uint64
          title: Settlement chain ID
        epochInfo:
          $ref: '#/components/schemas/ChainEpochInfo'
      title: Response message for getting last committed epoch
    ChainEpochInfo:
      type: object
      properties:
        lastCommittedEpoch:
          type: string
          format: uint64
          title: Last committed epoch for this chain
        startTime:
          type: string
          format: date-time
          title: Epoch start time
      title: Settlement chain with its last committed epoch
    Status:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Any'
    ListenProofsResponse:
      type: object
      properties:
        requestId:
          type: string
          title: Id of the request
        epoch:
          type: string
          format: uint64
          title: Epoch number
        aggregationProof:
          $ref: '#/components/schemas/AggregationProof'
          title: Final aggregation proof
      title: Response message for aggregation proofs stream
    GetSignaturesByEpochResponse:
      type: object
      properties:
        signatures:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Signature'
          title: List of signatures
        nextFrom:
          type: string
          description: Cursor to retrieve the next page. Empty when this is the last page.
      title: Response message for getting signatures by epoch
    SignMessageResponse:
      type: object
      properties:
        requestId:
          type: string
          title: Hash of the signature request
        epoch:
          type: string
          format: uint64
          title: Epoch number
      title: Response message for sign message request
    GetLocalValidatorResponse:
      type: object
      properties:
        validator:
          $ref: '#/components/schemas/Validator'
          title: The validator
      title: Response message for getting local validator
    GetCurrentEpochResponse:
      type: object
      properties:
        epoch:
          type: string
          format: uint64
          title: Epoch number
        startTime:
          type: string
          format: date-time
       

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/symbiotic/refs/heads/main/openapi/symbiotic-symbioticapiservice-api-openapi.yml