Reference
Registry XRPC API
Search, paginate, resolve and upload FluentCI Wasm plugins through io.fluentci endpoints.
API origin and records
The default CLI registry origin is https://api.fluentci.io. Deployments can use
another origin. A record is published to the user's PDS under io.fluentci.plugin
with record key name-version. Its author must match the repository DID.
Package views include record uri, cid, name, description, version,
publishedAt, author, license, url, sha256, and size.
GET / displays the FluentCI ASCII welcome page with website and documentation
links. API methods are under /xrpc.
GET /xrpc/_health returns { "status": "ok" } when the HTTP application is running.
GET /health remains available as a compatibility alias.
It is a liveness check, not a test of S3 permissions or Jetstream connectivity.
Search packages
GET /xrpc/io.fluentci.registry.searchPackages accepts:
| Parameter | Contract |
|---|---|
q |
Required text, 1–200 characters |
author |
Optional handle or DID |
limit |
1–100, default 20 |
cursor |
Optional opaque query-bound cursor |
curl -sS --get https://api.fluentci.io/xrpc/io.fluentci.registry.searchPackages \
--data-urlencode 'q=rust comp' \
--data-urlencode 'limit=20'
The response contains packages and an optional cursor. FTS5 token-prefix
search covers names and descriptions, normalizes accents, combines words with
AND, and excludes internally hidden records and inactive authors. Results retain stable
publication-time/URI pagination rather than exposing arbitrary FTS syntax.
List and resolve
GET /xrpc/io.fluentci.registry.listPackages accepts author, limit, and
cursor, without q, and returns the same page shape.
GET /xrpc/io.fluentci.registry.getPackage requires name and optionally accepts
version and author. It returns { "package": ... }. Supply the publisher
when multiple authors share a name. Without a version it selects the latest
stable SemVer, falling back to a prerelease only if no stable release exists.
Errors include PackageNotFound, AmbiguousPackage, and InvalidCursor.
Cursors belong to their original search/filter; do not reuse one with a changed
query or author. The SQL constraint prevents duplicate publisher/name/version
records while allowing different publishers and new versions.
Actor publications
GET /xrpc/io.fluentci.registry.getActorPackages requires actor (handle or
DID), and accepts limit (1–100, default 20) and cursor. It returns
{ "packages": [...], "cursor": "..." }, with the cursor omitted on the last page.
Handles resolve to DIDs before lookup. Results include all indexed versions,
ordered by publication time and record URI, and exclude internally hidden records and
inactive accounts. Cursors are bound to the resolved actor.
curl -sS --get https://api.fluentci.io/xrpc/io.fluentci.registry.getActorPackages \
--data-urlencode 'actor=alice.example' --data-urlencode 'limit=20'
Package metadata fields
Records and package views include name, description, version, publishedAt,
author, license, url, sha256, and size. Package views also include uri
and cid. Optional repository and subdir describe the source Git repository
and module directory. Optional logo is an HTTP(S) picture URL. Optional functions contains exported jobs with name,
wasmParams, wasmResults, and optional description, args, and returnType.
Each argument has name and type, with an optional description.
Function ABI data comes from the Wasm artifact. Source-level inputs and outputs come from declarations or a manifest; omission means unknown. Existing records without the new optional fields remain valid. See publishing for the portable metadata format shared by all SDKs.
Upload
POST /xrpc/io.fluentci.registry.publish receives raw application/wasm bytes,
not multipart form data. It requires a short-lived AT Protocol service-auth
Bearer token scoped to that method and the configured service DID. It does not
accept an app password as its upload credential.
Supply name and version together as query parameters for a versioned URL:
https://mod.fluentci.io/@alice.example/hello-ci/v1.0.0/hello-ci.wasm. The
server resolves and verifies the handle from the authenticated DID; callers
cannot choose another publisher's path. Metadata uses bare SemVer (1.0.0),
while URL version segments include v. Existing versioned objects cannot be
overwritten (PackageVersionExists). Omitting both parameters preserves legacy
content-addressed upload URLs.
curl -sS 'https://api.fluentci.io/xrpc/io.fluentci.registry.publish?name=hello-ci&version=1.0.0' \
-H "Authorization: Bearer $SERVICE_AUTH_TOKEN" \
-H 'Content-Type: application/wasm' \
--data-binary @dist/plugin.wasm
The response contains url, sha256, and size. The server validates Wasm and
limits uploads to 64 MiB, then stores an immutable object in S3. Errors include
InvalidWasm, authentication failures, and StorageUnavailable. The publisher
must subsequently create the PDS record; upload alone does not publish metadata.
Use fluentci publish to orchestrate both steps.
Indexing and definitions
Jetstream connections index valid plugin records into SQLite. Independent source cursors and durable event identities make overlapping streams/replays safe. This is asynchronous indexing, not an immediate cross-service transaction or a complete historical backfill.
Pkl definitions in apps/api/pkl/defs generate JSON lexicons, Gleam models and
encoders, and the runtime schema bundle. Run bun run lexicons:generate or
bun run lexicons:check in that workspace after changing Pkl sources. See
registry development for the implementation layout.
Published download URLs, SHA-256 checksums, and versions are immutable. Jetstream metadata updates cannot replace them, and module delete events are ignored.
Publisher module profiles
io.fluentci.registry.getActorPackages accepts an actor handle or DID. latest=true
returns one most recently published version per module name; q filters this list
using FTS. Responses include total (the actor's unfiltered visible module count)
and an optional query-bound cursor. Omit latest to retain the version feed.
The landing profile routes /:handle and /:did use these fields for filtering,
infinite loading, and exact counts. Author handles link to these internal profiles.