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. Used internally by @ceramicnetwork/http-client.
{
"openapi": "3.0.3",
"info": {
"title": "Ceramic HTTP 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": "Streams",
"description": "Create and load Ceramic streams by StreamID or CommitID"
},
{
"name": "Commits",
"description": "Apply commits to existing streams and retrieve stream commit history"
},
{
"name": "Multiqueries",
"description": "Batch-load multiple streams in a single request"
},
{
"name": "Pins",
"description": "Manage persistent pinning of streams on the local node"
},
{
"name": "Node",
"description": "Node health and configuration information"
}
],
"paths": {
"/api/v0/streams": {
"post": {
"tags": ["Streams"],
"summary": "Create Stream",
"description": "Creates a new Ceramic stream with a genesis commit. Returns the new StreamID and initial state.",
"operationId": "createStream",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStreamRequest"
},
"example": {
"type": 0,
"genesis": {
"header": {
"controllers": ["did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"]
},
"content": {
"name": "Alice",
"description": "My decentralized profile"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Stream created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StreamState"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v0/streams/{streamId}": {
"get": {
"tags": ["Streams"],
"summary": "Get Stream",
"description": "Loads a Ceramic stream by its StreamID. Optionally load a specific commit using a CommitID.",
"operationId": "getStream",
"parameters": [
{
"name": "streamId",
"in": "path",
"required": true,
"description": "The StreamID or CommitID of the stream to load",
"schema": {
"type": "string",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
}
}
],
"responses": {
"200": {
"description": "Stream state retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StreamState"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/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"
}
}
}
}
}
}
},
"/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"
}
}
}
}
}
}
},
"/api/v0/pins/{streamId}": {
"get": {
"tags": ["Pins"],
"summary": "Get Pin Status",
"description": "Retrieves the pinning status of a stream on the local Ceramic node.",
"operationId": "getPinStatus",
"parameters": [
{
"name": "streamId",
"in": "path",
"required": true,
"description": "The StreamID to check pin status for",
"schema": {
"type": "string",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
}
}
],
"responses": {
"200": {
"description": "Pin status retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinStatusResponse"
}
}
}
},
"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"
}
}
}
}
}
},
"post": {
"tags": ["Pins"],
"summary": "Pin Stream",
"description": "Pins a stream to the local Ceramic node, ensuring it is persistently stored and not garbage collected.",
"operationId": "pinStream",
"parameters": [
{
"name": "streamId",
"in": "path",
"required": true,
"description": "The StreamID to pin",
"schema": {
"type": "string",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
}
}
],
"responses": {
"200": {
"description": "Stream pinned successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinResponse"
}
}
}
},
"400": {
"description": "Invalid stream ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["Pins"],
"summary": "Unpin Stream",
"description": "Removes the pin for a stream from the local Ceramic node, allowing it to be garbage collected.",
"operationId": "unpinStream",
"parameters": [
{
"name": "streamId",
"in": "path",
"required": true,
"description": "The StreamID to unpin",
"schema": {
"type": "string",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
}
}
],
"responses": {
"200": {
"description": "Stream unpinned successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinResponse"
}
}
}
},
"404": {
"description": "Stream not pinned or 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/node/healthcheck": {
"get": {
"tags": ["Node"],
"summary": "Node Healthcheck",
"description": "Verifies the Ceramic node is operational and ready to serve requests.",
"operationId": "nodeHealthcheck",
"responses": {
"200": {
"description": "Node is healthy",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "Alive!"
}
}
}
},
"503": {
"description": "Node is not healthy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v0/node/chains": {
"get": {
"tags": ["Node"],
"summary": "Supported Chains",
"description": "Lists the blockchain networks (CAIP-2 chain IDs) supported by this Ceramic node for anchoring.",
"operationId": "getSupportedChains",
"responses": {
"200": {
"description": "List of supported chain IDs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupportedChainsResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"CreateStreamRequest": {
"type": "object",
"required": ["type", "genesis"],
"properties": {
"type": {
"type": "integer",
"description": "Stream type identifier (0 = TileDocument, 1 = CAIP-10Link, 3 = Model, 4 = ModelInstanceDocument)",
"example": 0
},
"genesis": {
"$ref": "#/components/schemas/GenesisCommit"
},
"opts": {
"$ref": "#/components/schemas/StreamOptions"
}
}
},
"GenesisCommit": {
"type": "object",
"properties": {
"header": {
"$ref": "#/components/schemas/CommitHeader"
},
"content": {
"description": "Initial content of the stream (stream-type dependent)",
"nullable": true
}
}
},
"CommitHeader": {
"type": "object",
"properties": {
"controllers": {
"type": "array",
"description": "DID or CAIP-10 account strings that control this stream",
"items": {
"type": "string"
},
"example": ["did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"]
},
"family": {
"type": "string",
"description": "Optional schema family identifier for grouping streams"
},
"schema": {
"type": "string",
"description": "Optional CommitID of the schema stream to validate content against"
},
"tags": {
"type": "array",
"description": "Optional tags for categorizing the stream",
"items": {
"type": "string"
}
}
}
},
"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"
}
}
},
"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
}
}
},
"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"
}
}
}
}
},
"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"
}
}
}
}
}
},
"MultiQueryRequest": {
"type": "object",
"required": ["queries"],
"properties": {
"queries": {
"type": "array",
"description": "Array of stream queries to execute in batch",
"items": {
"$ref": "#/components/schemas/StreamQuery"
}
}
}
},
"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"
}
}
},
"MultiQueryResponse": {
"type": "object",
"description": "Map of StreamID to stream state for all queried streams",
"additionalProperties": {
"$ref": "#/components/schemas/StreamState"
}
},
"PinStatusResponse": {
"type": "object",
"properties": {
"streamId": {
"type": "string",
"description": "The StreamID",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
},
"pinnedStreamIds": {
"type": "array",
"description": "List of pinned StreamIDs (contains the requested ID if pinned)",
"items": {
"type": "string"
}
}
}
},
"PinResponse": {
"type": "object",
"properties": {
"streamId": {
"type": "string",
"description": "The StreamID that was pinned or unpinned",
"example": "kjzl6cwe1jw147ww5d8pswh1hjh686257r81ifgom1bou37r6vgdmk7jtnka91t"
},
"isPinned": {
"type": "boolean",
"description": "Whether the stream is now pinned"
}
}
},
"SupportedChainsResponse": {
"type": "object",
"properties": {
"supportedChains": {
"type": "array",
"description": "CAIP-2 chain IDs supported by this node for anchoring",
"items": {
"type": "string"
},
"example": ["eip155:1", "eip155:5"]
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Human-readable error message"
}
}
}
}
}
}