<!-- Generated by scripts/gen-api-reference.js — do not edit by hand. --> <!-- Run npm run gen:api-reference to regenerate. -->

Built-in API reference

This page lists every method in the static RPC manifests of the server's built-in plugins. It is generated from the shared plugin registry in lib/builtin-plugins.js, so it stays in lock-step with what the server actually mounts at startup. Hand-written summaries live in docs/api-notes.json.

Coverage and boundaries

Included: the root database (lib/db) and every RPC-bearing built-in plugin — the complete set of methods this server exposes from its own static manifests.

Excluded by design:

• Dynamically installed user plugins (loaded by ssb-plugins at runtime).
• Non-manifest secret-stack core methods such as auth, address, manifest, multiserver, multiserverNet, which the framework adds to a live server but does not declare in a repository manifest.

Methods that do not yet have prose are shown as _Not yet documented._. The coverage count in the footer tracks documentation progress.

Root database (lib/db)

Methods on the server's root object. These are called without a namespace prefix (e.g. publish, whoami).

get — async

Fetch a single message by its key (message id).

Arguments:

• key — the message id (%...sha256), or an options object

Example:

ssb-server get '%abc...=.sha256'

add — async

Append an already-formed, validly-signed message to the local store without re-signing it. Used when ingesting messages from other feeds.

Arguments:

• msg — a complete signed SSB message

publish — async

Publish a new message to the local feed using the current identity, signing and appending it to the log.

Arguments:

• content — the message content object; must include a type string

Example:

ssb-server publish --type post --text 'hello world'

del — async

Delete a message or feed from the local store. Destructive and local-only; it does not unpublish anything that has already been replicated to peers.

queue — async

Queue a raw message for validation and storage without immediately flushing it to disk.

flush — async

Flush any queued writes, calling back once they are durably stored.

search — async

Low-level full-store search hook exposed by the database. Most callers should prefer messagesByType or links.

createLogStream — source

Stream messages in the order the local node received them. Supports limit, reverse, live, gt/gte/lt/lte, and keys/values options.

Example:

ssb-server createLogStream --limit 10 --reverse

createFeedStream — source

Stream messages ordered by their claimed timestamp. Honors gt/gte/lt/lte range filters on the timestamp, plus limit, reverse, and live.

createHistoryStream — source

Stream the messages of a single feed in sequence order, optionally starting from a given sequence. This is the core replication read used over the wire.

Arguments:

• id — the feed id (@...ed25519)
• seq — start at this sequence number
• live — keep the stream open for new messages

Example:

ssb-server createHistoryStream --id '@me=.ed25519' --seq 1

createUserStream — source

Stream one feed's messages much like createHistoryStream, with the log-stream option shape (limit, reverse, gt/lt on sequence).

createWriteStream — sink

Sink that accepts messages and adds each one to the local store, the streaming counterpart of add.

createSequenceStream — source

Stream the local store's overall sequence as it advances; useful for tracking write progress.

messagesByType — source

Stream every message of a given type across all known feeds. This is the primary index used by Decent and ssbski to build their feeds.

Arguments:

• type — the message type to filter on
• live — keep streaming new matches
• reverse — newest first

Example:

ssb-server messagesByType --type post --reverse --limit 20

links — source

Traverse link relationships between messages and feeds (e.g. who mentioned a message). Filter by source, dest, rel, and values.

latest — source

Stream the latest sequence for every feed in the local database (not only followed feeds), emitting { id, sequence, ts } records.

getLatest — async

Get the latest message for a single feed.

Arguments:

• id — the feed id

latestSequence — async

Get the latest known sequence number (and timestamp) for a feed without returning the whole message.

Arguments:

• id — the feed id

getVectorClock — async

Return a map of every known feed to its latest sequence — a vector clock of local replication state.

getAtSequence — async

Fetch the message at a specific [feedId, sequence] position.

Arguments:

• seq — a [feedId, sequence] pair

whoami — sync

Return the current local identity as { id }.

Example:

ssb-server whoami

ready — sync

Report whether the database has finished its initial load and is ready to serve reads.

progress — sync

Return indexing/replication progress counters, used to drive the startup progress bar.

status — sync

Return a snapshot of runtime status, including database and (when available) local-peer state.

version — sync

Return the running server version (the package version).

help — sync

Return inline help describing the methods available on the root object.

plugins

Provided by the ssb-plugins plugin.

plugins.install — source

Install a user plugin from npm into the configuration directory and stream installation output. Restart is required for it to load.

plugins.uninstall — source

Remove a previously installed user plugin, streaming the npm output.

plugins.enable — async

Mark an installed user plugin as enabled so it loads on the next start.

plugins.disable — async

Mark an installed user plugin as disabled so it is skipped on the next start.

plugins.help — sync

Return inline help for the plugins namespace.

gossip

Provided by the ssb-gossip plugin.

gossip.add — sync

Register a peer address in the gossip table so the server may connect to it.

Arguments:

• addr — a multiserver address
• source — where the address came from (e.g. manual)

gossip.remove — sync

Remove a peer from the gossip table.

gossip.connect — async

Connect immediately to a peer by multiserver address.

Arguments:

• addr — a multiserver address

Example:

ssb-server gossip.connect 'net:1.2.3.4:8008~shs:KEY'

gossip.disconnect — async

Drop an existing connection to a peer.

gossip.changes — source

Stream gossip table change events as peers are added, connected, or dropped.

gossip.reconnect — sync

Reset connections so the server retries peers from scratch.

gossip.disable — sync

Disable a gossip transport or behavior at runtime.

gossip.enable — sync

Enable a gossip transport or behavior at runtime.

gossip.ping — duplex

Duplex keep-alive used between connected peers to measure liveness and clock skew.

gossip.get — sync

Look up the gossip table entry for a specific peer.

gossip.peers — sync

Return the current list of known peers and their connection state.

Example:

ssb-server gossip.peers

gossip.help — sync

Return inline help for the gossip namespace.

replicate — stub

Provided by the ssb-replicate-stub plugin. This is a compatibility stub; its methods are present for protocol compatibility but do little or no work in this build.

replicate.request — sync

Stub / no-op in this build. Historically, ask the replicator to (stop) replicating a feed. Replication here is handled by ebt.

replicate.block — sync

Stub / no-op in this build. Historically, mark a feed as blocked from replication. Retained for compatibility; blocking is expressed through the social graph.

ebt

Provided by the ssb-ebt plugin.

ebt.replicate — duplex

Epidemic broadcast tree replication: the duplex stream peers use to exchange feed updates efficiently.

ebt.request — sync

Tell EBT to start or stop replicating a given feed.

Arguments:

• id — the feed id
• replicate — boolean: whether to replicate it

ebt.block — sync

Tell EBT to refuse replicating a feed for a given peer relationship.

ebt.peerStatus — sync

Return EBT's view of replication progress for each peer and feed.

friends

Provided by the friends plugin.

friends.hopStream — source

Stream changes to the hop-distance graph as follows and blocks are processed.

friends.onEdge — sync

Subscribe to individual follow/block edge changes in the social graph.

friends.isFollowing — async

Report whether one feed follows another.

Arguments:

• source — the follower feed id
• dest — the followed feed id

friends.isBlocking — async

Report whether one feed blocks another.

Arguments:

• source — the blocking feed id
• dest — the blocked feed id

friends.hops — async

Return a map of feed id to hop distance from the local identity (0 = self, 1 = followed, etc.), the set used to decide what to replicate.

Example:

ssb-server friends.hops

friends.help — sync

Return inline help for the friends namespace.

friends.get — async

Return the raw follow/block graph as nested { source: { dest: state } } maps.

Example:

ssb-server friends.get

friends.createFriendStream — source

Stream feed ids within a hop range, optionally live, as the graph grows.

friends.stream — source

Stream the full hops state and subsequent updates as a single live view.

blobs

Provided by the ssb-blobs plugin.

blobs.get — source

Stream the bytes of a blob by its hash id.

Arguments:

• hash — the blob id (&...sha256)

Example:

ssb-server blobs.get '&abc...=.sha256'

blobs.getSlice — source

Stream a byte range of a blob, given { key, start, end }.

blobs.add — sink

Sink that stores incoming bytes as a content-addressed blob and calls back with its hash. The CLI blobs.add wrapper feeds a file or stdin into it.

Example:

cat photo.png | ssb-server blobs.add

blobs.rm — async

Remove a blob from the local store.

blobs.ls — source

Stream the hashes of all blobs currently held locally.

blobs.has — async

Report whether one or more blobs are present locally.

Arguments:

• hash — a blob id or array of ids

blobs.size — async

Return the byte size of a locally-held blob, or null if absent.

blobs.meta — async

Return metadata about the blob store or a specific blob.

blobs.want — async

Register interest in a blob so the server fetches it from peers that have it, calling back when it arrives.

Arguments:

• hash — the blob id to fetch

Example:

ssb-server blobs.want '&abc...=.sha256'

blobs.push — async

Actively push a blob out to peers rather than waiting for them to want it.

blobs.changes — source

Stream notifications as blobs are added to the local store.

blobs.createWants — source

Stream the current want-list — blobs this node is seeking — used during peer exchange.

blobs.help — sync

Return inline help for the blobs namespace.

invite

Provided by the invite plugin.

invite.create — async

Create an invite code that another peer can redeem to connect to and be followed by this server.

Arguments:

• opts — a number of uses, or an options object such as { uses, modern }

Example:

ssb-server invite.create 1

invite.use — async

Server side of redemption: accept a redeeming peer, follow them, and confirm the invite.

Arguments:

• req — the redemption request { feed }

invite.accept — async

Client side of redemption: connect to the inviting pub using an invite code, request access, and publish a follow.

Arguments:

• invite — the invite code string

Example:

ssb-server invite.accept 'host:port:@key=.ed25519~SEED'

git

Provided by the git-server plugin.

git.create — async

Create a new git repository feed message, returning the repo id used by the git-over-SSB / git-over-HTTP server.

Example:

ssb-server git.create --name my-repo

query — stub

Provided by the ssb-query plugin. This is a compatibility stub; its methods are present for protocol compatibility but do little or no work in this build.

query.read — source

Stub / no-op in this build. Unsupported compatibility method. This fails with an explicit error in SQLite mode; use messagesByType or root links instead.

Arguments:

• query — a flumeview-query spec ($filter, $map, etc.)

query.explain — sync

Stub / no-op in this build. Return the index and plan a given query would use, for debugging query selection.

query.help — sync

Stub / no-op in this build. Return inline help for the query namespace.

links2

Provided by the ssb-links plugin.

links2.read — source

Stream link relationships between messages and feeds with filtering on source, dest, and rel. This is the working link index in this build (links on the root delegates to the same data).

Arguments:

• query — a links query, e.g. { source, dest, rel, values: true }

links2.help — sync

Return inline help for the links2 namespace.

ooo — stub

Provided by the ssb-ooo-stub plugin. This is a compatibility stub; its methods are present for protocol compatibility but do little or no work in this build.

ooo.stream — duplex

Stub / no-op in this build. Out-of-order message stream. This build ships a stub, so the stream yields nothing.

ooo.get — async

Stub / no-op in this build. Fetch an out-of-order message by id. Stubbed in this build.

ooo.help — sync

Stub / no-op in this build. Return inline help for the ooo namespace.

Coverage: 83 of 83 built-in static manifest methods documented.