openapi.yaml

openapi: 3.0.0
info:
  description: |
    This is the Ceramic API for working with streams and events
  license:
    name: MIT
    url: https://mit-license.org/
  title: Ceramic API
  version: 0.56.0
servers:
- url: /ceramic
paths:
  /liveness:
    get:
      responses:
        "200":
          description: success
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Test the liveness of the Ceramic node
    options:
      responses:
        "200":
          description: cors
      summary: cors
  /debug/heap:
    get:
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the heap statistics of the Ceramic node
    options:
      responses:
        "200":
          description: cors
      summary: cors
  /version:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
          description: success
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the version of the Ceramic node
    options:
      responses:
        "200":
          description: cors
      summary: cors
    post:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
          description: success
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the version of the Ceramic node
  /events:
    options:
      responses:
        "200":
          description: cors
      summary: cors
    post:
      requestBody:
        $ref: '#/components/requestBodies/EventData'
      responses:
        "204":
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Creates a new event
  /events/{event_id}:
    get:
      parameters:
      - description: "CID of the root block of the event, used to identify of the\
          \ event"
        explode: false
        in: path
        name: event_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "404":
          content:
            text/plain:
              schema:
                type: string
          description: Event not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get event data
    options:
      parameters:
      - description: Name of the field in the Events header that holds the separator
          value e.g. 'model'
        explode: false
        in: path
        name: event_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          description: cors
      summary: cors
  /streams/{stream_id}:
    get:
      parameters:
      - description: Multibase encoded stream ID
        explode: false
        in: path
        name: stream_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamState'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "404":
          content:
            text/plain:
              schema:
                type: string
          description: Stream not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get stream state
    options:
      parameters:
      - description: Multibase encoded stream ID
        explode: false
        in: path
        name: stream_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          description: cors
      summary: cors
  /interests/{sort_key}/{sort_value}:
    options:
      parameters:
      - description: Name of the field in the Events header that holds the separator
          value e.g. 'model'
        explode: false
        in: path
        name: sort_key
        required: true
        schema:
          type: string
        style: simple
      - description: The value of the field in the Events header indicated by the
          separator key e.g. multibase encoded model ID
        explode: false
        in: path
        name: sort_value
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          description: cors
      summary: cors
    post:
      parameters:
      - description: name of the sort_key
        explode: false
        in: path
        name: sort_key
        required: true
        schema:
          type: string
        style: simple
      - description: value associated with the sort key
        explode: false
        in: path
        name: sort_value
        required: true
        schema:
          type: string
        style: simple
      - description: the controller to register interest for
        explode: true
        in: query
        name: controller
        required: false
        schema:
          type: string
        style: form
      - description: the stream to register interest for
        explode: true
        in: query
        name: streamId
        required: false
        schema:
          type: string
        style: form
      responses:
        "204":
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Register interest for a sort key
  /interests:
    options:
      responses:
        "200":
          description: cors
      summary: cors
    post:
      requestBody:
        $ref: '#/components/requestBodies/Interest'
      responses:
        "204":
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Register interest for a sort key
  /config/network:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkInfo'
          description: success
      summary: Get info about the Ceramic network the node is connected to
    options:
      responses:
        "200":
          description: cors
      summary: cors
  /experimental/interests:
    get:
      parameters:
      - description: Only return interests from the specified peer ID.
        explode: true
        in: query
        name: peerId
        required: false
        schema:
          type: string
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterestsGet'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the interests stored on the node
    options:
      parameters:
      - description: Only return interests from the specified peer ID.
        explode: true
        in: query
        name: peerId
        required: false
        schema:
          type: string
        style: form
      responses:
        "200":
          description: cors
      summary: cors
  /experimental/events/{sep}/{sepValue}:
    get:
      parameters:
      - description: Name of the field in the Events header that holds the separator
          value e.g. 'model'
        explode: false
        in: path
        name: sep
        required: true
        schema:
          type: string
        style: simple
      - description: The value of the field in the Events header indicated by the
          separator key e.g. multibase encoded model ID
        explode: false
        in: path
        name: sepValue
        required: true
        schema:
          type: string
        style: simple
      - description: the controller to filter (DID string)
        explode: true
        in: query
        name: controller
        required: false
        schema:
          type: string
        style: form
      - description: the stream to filter (multibase encoded stream ID)
        explode: true
        in: query
        name: streamId
        required: false
        schema:
          type: string
        style: form
      - description: "token that designates the point to resume from, that is find\
          \ keys added after this point"
        explode: true
        in: query
        name: offset
        required: false
        schema:
          type: integer
        style: form
      - description: "the maximum number of events to return, default is 10000."
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsGet'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get events matching the interest stored on the node
    options:
      parameters:
      - description: Name of the field in the Events header that holds the separator
          value e.g. 'model'
        explode: false
        in: path
        name: sep
        required: true
        schema:
          type: string
        style: simple
      - description: The value of the field in the Events header indicated by the
          separator key e.g. multibase encoded model ID
        explode: false
        in: path
        name: sepValue
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          description: cors
      summary: cors
  /feed/events:
    get:
      parameters:
      - description: "token that designates the point to resume from, that is find\
          \ keys added after this point"
        explode: true
        in: query
        name: resumeAt
        required: false
        schema:
          type: string
        style: form
      - description: "The maximum number of events to return, default is 100. The\
          \ max with data is 10000."
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: |
          Whether to include the event data (carfile) in the response. In the future, only the payload or other options may be supported:
            * `none` - Empty, only the event ID is returned
            * `full` - The entire event carfile (including the envelope and payload)
        explode: true
        in: query
        name: includeData
        required: false
        schema:
          enum:
          - none
          - full
          type: string
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventFeed'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get all new event keys since resume token
    options:
      responses:
        "200":
          description: cors
      summary: cors
  /feed/resumeToken:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_feed_resumeToken_get_200_response'
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the current (maximum) highwater mark/continuation token of the
        feed. Allows starting `feed/events` from 'now'.
    options:
      responses:
        "200":
          description: cors
      summary: cors
  /peers:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peers'
          description: success
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get list of connected peers
    options:
      parameters:
      - description: "Multiaddress of peer to connect to, at least one address must\
          \ contain the peer id."
        explode: true
        in: query
        name: addresses
        required: true
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        "200":
          description: cors
      summary: cors
    post:
      parameters:
      - description: "Multiaddress of peer to connect to, at least one address must\
          \ contain the peer id."
        explode: true
        in: query
        name: addresses
        required: true
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        "204":
          description: success
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Connect to a peer
components:
  requestBodies:
    EventData:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EventData'
      description: Event to add to the node
      required: true
    Message:
      content:
        application/cbor-seq:
          schema:
            format: byte
            type: string
      description: Recon message to send
      required: true
    Interest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Interest'
      description: Interest to register on the node
      required: true
  schemas:
    Version:
      description: "Version of the Ceramic node in semver format, e.g. 2.1.0"
      example:
        version: version
      properties:
        version:
          description: Version of the Ceramic node
          type: string
    BadRequestResponse:
      description: Bad request (input error)
      properties:
        message:
          description: Message describing the error
          type: string
      required:
      - message
      title: Response to a bad request (400)
      type: object
    Event:
      description: A Ceramic event as part of a Ceramic Stream. Contains both the
        root CID used to identify the Event as well as the Event payload data.
      example:
        data: data
        id: id
      properties:
        id:
          description: Multibase encoding of event root CID bytes.
          type: string
        data:
          description: Multibase encoding of event data.
          type: string
      required:
      - id
      title: A Ceramic Event
      type: object
    EventData:
      description: The data for a Ceramic event that is part of a Ceramic Stream
      example:
        data: data
      properties:
        data:
          description: Multibase encoding of event data.
          type: string
      required:
      - data
      title: A Ceramic Event Data Payload
      type: object
    EventFeed:
      description: Ceramic event keys as part of a Ceramic Stream
      example:
        resumeToken: resumeToken
        events:
        - data: data
          id: id
        - data: data
          id: id
      properties:
        events:
          description: "An array of events. For now, the event data payload is empty."
          items:
            $ref: '#/components/schemas/Event'
          type: array
        resumeToken:
          description: The token/highwater mark to used as resumeAt on a future request
          type: string
      required:
      - events
      - resumeToken
      title: Ceramic Event feed data
      type: object
    EventsGet:
      description: Ceramic event keys as part of a Ceramic Stream
      example:
        resumeOffset: 0
        events:
        - data: data
          id: id
        - data: data
          id: id
        isComplete: true
      properties:
        events:
          description: An array of events
          items:
            $ref: '#/components/schemas/Event'
          type: array
        resumeOffset:
          description: An integer specifying where to resume the request. Only works
            correctly for the same input parameters.
          type: integer
        isComplete:
          description: A boolean specifying if there are more events to be fetched.
            Repeat with the resumeOffset to get next set.
          type: boolean
      required:
      - events
      - isComplete
      - resumeOffset
      title: Information about multiple events.
      type: object
    InterestsGet:
      description: Ceramic interest keys
      example:
        interests:
        - data: data
        - data: data
      properties:
        interests:
          description: An array of interests
          items:
            $ref: '#/components/schemas/InterestsGet_interests_inner'
          type: array
      required:
      - interests
      title: Information about multiple interests.
      type: object
    ErrorResponse:
      description: Error response
      properties:
        message:
          description: Error message
          type: string
      required:
      - message
      title: Error response
      type: object
    Interest:
      description: Describes a recon interest range to store and synchronize
      example:
        controller: controller
        streamId: streamId
        sepValue: sepValue
        sep: sep
      properties:
        sep:
          description: "Separator key, typically 'model' (sometimes called sort_key)"
          type: string
        sepValue:
          description: "Multibase encoded separator value (sometimes called sort_value,\
            \ typically a stream ID)"
          type: string
        controller:
          description: Decentralized identifier (DID) string
          type: string
        streamId:
          description: Multibase encoded stream ID.
          type: string
      required:
      - sep
      - sepValue
      title: A recon interest
      type: object
    NetworkInfo:
      description: Ceramic network information
      example:
        name: name
      properties:
        name:
          description: Name of the Ceramic network
          type: string
      required:
      - name
      title: Information about the Ceramic network
      type: object
    StreamState:
      description: The state of a Ceramic stream as defined by the stream type aggregation
        and conflict resolution rules.
      example:
        controller: controller
        data: data
        id: id
        event_cid: event_cid
        dimensions: "{}"
      properties:
        id:
          description: Multibase encoding of the stream id
          type: string
        event_cid:
          description: CID of the event that produced this state
          type: string
        controller:
          description: Controller of the stream
          type: string
        dimensions:
          description: "Dimensions of the stream, each value is multibase encoded."
          type: object
        data:
          description: Multibase encoding of the data of the stream. Content is stream
            type specific.
          type: string
      required:
      - controller
      - data
      - dimensions
      - event_cid
      - id
      title: State of a Ceramic stream
      type: object
    Peers:
      example:
        peers:
        - addresses:
          - addresses
          - addresses
          id: id
        - addresses:
          - addresses
          - addresses
          id: id
      properties:
        peers:
          items:
            $ref: '#/components/schemas/Peer'
          type: array
      required:
      - peers
      title: List of Peers
      type: object
    Peer:
      description: Information about a connected peer
      example:
        addresses:
        - addresses
        - addresses
        id: id
      properties:
        id:
          description: DID of peer
          type: string
        addresses:
          description: "List of known multiaddress of peer, will always include the\
            \ peer id"
          items:
            description: Multiaddress where peer may be dialed
            type: string
          type: array
      required:
      - addresses
      - id
      title: Information about a connected peer
      type: object
    _feed_resumeToken_get_200_response:
      example:
        resumeToken: resumeToken
      properties:
        resumeToken:
          description: The highwater mark/resume token to use with the event/feed
            endpoint.
          type: string
      required:
      - resumeToken
      type: object
    InterestsGet_interests_inner:
      example:
        data: data
      properties:
        data:
          description: The multbase encoded bytes of the interest.
          type: string
      required:
      - data
      type: object