API reference

Index snapshots

Pull, probe, list and publish shared team-index snapshots — plus the worker's CI publish endpoint.

Move a workspace's context index between machines: publish a snapshot once, pull it everywhere. All /index-snapshot calls use a Bearer prom_live_... key and are tenant-scoped — a selector your tenant does not own reads as "not found", never as someone else's data. Pull and publish also require the org-level shared-index opt-in (/app/settings).

Every request takes exactly one selector: workspaceId (a UUID) or repo (a normalized repo identity).

The context MCP server's pull_index tool wraps the pull path — see MCP tools.

GET /index-snapshot — pull

GET https://api.prom.codes/index-snapshot?repo=github.com/owner/repo

Returns the current snapshot's manifest plus a signed download URL:

{ "ok": true, "manifest": { "…": "…" }, "signedUrl": "https://…", "expiresIn": 300 }

Any miss (no snapshot, unowned selector, opt-in disabled) is 404 NO_SNAPSHOT.

`?probe=1` — membership probe

Metadata only, no signed URL. Misses are data, not errors:

{ "ok": true, "exists": true, "gitSha": "…", "builtAt": "…", "sizeBytes": 123,
  "fileCount": 240, "symbolCount": 1812, "embeddingModel": "…", "isCurrent": true }

A repo not in the cloud returns 200 with { "ok": true, "exists": false }.

`?list=1` — cloud roster

No selector. Returns every workspace of your tenant with its current snapshot summary (workspaceId, repo, defaultBranch, inCloud, gitSha, builtAt, sizeBytes, fileCount, symbolCount) plus sharedIndexEnabled. Works even before the opt-in.

POST /index-snapshot — publish

Two-step: sign, upload, commit. The artifact bytes go straight to storage — never through this endpoint.

{ "op": "sign", "manifest": { … }, "repo": "…" } → { "ok": true, "uploadUrl": "…", "storagePath": "…" }. Upload the artifact with an HTTP PUT to uploadUrl.
{ "op": "commit", "manifest": { … }, "sizeBytes": 123, "repo": "…" } → { "ok": true, "storagePath": "…", "gitSha": "…" } — flips the current-snapshot pointer.

manifest is the snapshot manifest the client built (gitSha, checksum, compression, fileCount, symbolCount, embedding metadata, …).

Errors

Envelope: { "ok": false, "code": "…", "error": "…" }.

Status	Code	Where
400	`INVALID_BODY` / `INVALID_SELECTOR`	Bad body or selector.
401	`INVALID_API_KEY`	Missing or invalid key.
403	`SHARED_INDEX_DISABLED`	Publish without the org opt-in.
403	`WORKSPACE_LIMIT`	Auto-provisioning cap reached.
404	`NO_SNAPSHOT` (GET) / `NO_WORKSPACE` (POST)	Selector resolved to nothing.
500	`LOOKUP_FAILED` / `COMMIT_FAILED`	Database read/write failed.
502	`SIGN_FAILED` / `SIGN_UPLOAD_FAILED`	Could not mint a signed URL.

Worker POST /snapshot — CI publish

The indexer worker builds and publishes a snapshot itself (the CI path). Auth is the worker token, not an API key:

POST https://api.prom.codes/snapshot
Authorization: Bearer <PROMETHEUS_WORKER_TOKEN>

Body: { "tenantId": "<uuid>", "workspaceId": "<uuid>", "gitSha": "…", "source": { … }, "repoUrl": "…" } — source as in POST /index; repoUrl optional.

Replies 202 { "ok": true, "accepted": true } immediately and runs the job in the background — poll the pull endpoint for the result. Other answers: 400 BAD_* (ids must be UUIDs; gitSha required), 401 UNAUTHORIZED, 409 SNAPSHOT_IN_PROGRESS (one job at a time), 501 NOT_CONFIGURED (publishing disabled on this worker).

POST /index — plain hosted indexing.
MCP tools — pull_index and friends.
Tenant & workspace — ownership model.