fluentcidocs
Website GitHub

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.

Made with ♥ in Antananarivo, Madagascar.
Search documentation