openapi: 3.0.3
info:
  title: Ceramic HTTP Commits 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: Commits
  description: Apply commits to existing streams and retrieve stream commit history
paths:
  /api/v0/commits:
    post:
      tags:
      - Commits
      summary: Apply Commit
      description: Applies a new commit to an existing Ceramic stream, updating its state. Requires the StreamID and the commit data.
      operationId: applyCommit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyCommitRequest'
            example:
              streamId: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
              commit:
                value:
                  header:
                    controllers:
                    - did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
                  content:
                    name: Alice Updated
                    description: Updated decentralized profile
              opts: {}
      responses:
        '200':
          description: Commit applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamState'
        '400':
          description: Invalid commit or stream not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v0/commits/{streamId}:
    get:
      tags:
      - Commits
      summary: List Stream Commits
      description: Retrieves the complete list of commits for a given stream, ordered from genesis to latest.
      operationId: listStreamCommits
      parameters:
      - name: streamId
        in: path
        required: true
        description: The StreamID whose commit history to retrieve
        schema:
          type: string
          example: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
      responses:
        '200':
          description: List of commits retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitListResponse'
        '404':
          description: Stream not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CommitListResponse:
      type: object
      properties:
        streamId:
          type: string
          description: The StreamID
          example: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
        commits:
          type: array
          description: Ordered list of all commits from genesis to latest
          items:
            type: object
            properties:
              cid:
                type: string
                description: The CID of this commit
              value:
                type: object
                description: The raw commit payload
    ApplyCommitRequest:
      type: object
      required:
      - streamId
      - commit
      properties:
        streamId:
          type: string
          description: The StreamID of the stream to update
          example: kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t
        commit:
          type: object
          description: The signed commit object (JWS or CACAO-signed DAG-JOSE object)
          properties:
            value:
              type: object
              description: The commit payload (header + content delta)
        opts:
          $ref: '#/components/schemas/StreamOptions'
    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
    StreamOptions:
      type: object
      description: Optional stream operation configuration
      properties:
        anchor:
          type: boolean
          description: Whether to request an anchor for this commit
          default: true
        publish:
          type: boolean
          description: Whether to publish the commit to the Ceramic network
          default: true
        sync:
          type: integer
          description: 'Sync policy: 0=never, 1=prefer cache, 2=always sync'
          enum:
          - 0
          - 1
          - 2
          default: 1
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message