openapi: 3.0.3
info:
  title: Ceramic HTTP Commits Multiqueries API
  description: Low-level REST HTTP API for the Ceramic node (js-ceramic), providing the underlying transport for all Self.ID SDK operations. Exposes endpoints to create/load streams by StreamID or CommitID, batch-load streams via multiQuery, manage anchoring and pinning, and access the Data Feed for custom indexers.
  version: 0.1.0
  contact:
    name: Ceramic Network
    url: https://ceramic.network
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://gateway.ceramic.network
  description: Ceramic Gateway (read-only)
- url: https://ceramic-clay.3boxlabs.com
  description: Clay testnet node
tags:
- name: Multiqueries
  description: Batch-load multiple streams in a single request
paths:
  /api/v0/multiqueries:
    post:
      tags:
      - Multiqueries
      summary: Multi-Query Streams
      description: Batch-loads multiple streams in a single request. Each query specifies a StreamID and optional paths to related streams to load simultaneously.
      operationId: multiQueryStreams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiQueryRequest'
            example:
              queries:
              - streamId: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
                paths:
                - link
              - streamId: kjzl6cwe1jw14b9pq2o1bvmxzpbz8y3y6r5l9q3v2k7
                paths: []
      responses:
        '200':
          description: Streams retrieved successfully. Returns a map of StreamID to stream state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiQueryResponse'
        '400':
          description: Invalid query request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MultiQueryResponse:
      type: object
      description: Map of StreamID to stream state for all queried streams
      additionalProperties:
        $ref: '#/components/schemas/StreamState'
    StreamState:
      type: object
      description: The current state of a Ceramic stream
      properties:
        streamId:
          type: string
          description: The unique StreamID
          example: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
        state:
          type: object
          properties:
            type:
              type: integer
              description: Stream type identifier
              example: 0
            content:
              description: Current content of the stream
              example:
                name: Alice
                description: My decentralized profile
            metadata:
              type: object
              description: Stream metadata
              properties:
                controllers:
                  type: array
                  items:
                    type: string
                schema:
                  type: string
                  nullable: true
                family:
                  type: string
                  nullable: true
            signature:
              type: integer
              description: 'Signature status: 0=genesis unsigned, 1=genesis signed, 2=signed'
              enum:
              - 0
              - 1
              - 2
            anchorStatus:
              type: integer
              description: 'Anchoring status: 0=not requested, 1=pending, 2=processing, 3=anchored, 4=failed'
              enum:
              - 0
              - 1
              - 2
              - 3
              - 4
            log:
              type: array
              description: Ordered list of CIDs representing the commit log
              items:
                type: object
                properties:
                  cid:
                    type: string
                  type:
                    type: integer
            next:
              type: object
              nullable: true
              description: Pending content not yet anchored
    StreamQuery:
      type: object
      required:
      - streamId
      properties:
        streamId:
          type: string
          description: The StreamID to load
          example: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
        paths:
          type: array
          description: Optional paths to related streams to load in the same query
          items:
            type: string
          example:
          - link
        atTime:
          type: integer
          description: Optional Unix timestamp to load stream state at a specific point in time
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
    MultiQueryRequest:
      type: object
      required:
      - queries
      properties:
        queries:
          type: array
          description: Array of stream queries to execute in batch
          items:
            $ref: '#/components/schemas/StreamQuery'