API reference

POST /embed & /rerank

The metered embedding and re-ranking proxy — vectors and relevance scores for your prom_live_ key, billed in credits.

Send code or text, get vectors (/embed) or relevance scores (/rerank). Both routes live at api.prom.codes (also reachable as prom.codes/api/v1/…) and require a tenant API key:

Authorization: Bearer prom_live_...

The response never names the upstream provider or model — clients get an opaque fingerprint instead. When the upstream changes, the fingerprint changes and clients know to re-embed.

POST /embed

{ "input": ["function add(a, b) { return a + b }"], "inputType": "query" }

input: 1–128 non-empty strings, at most 480,000 characters in total.
inputType: "document" (default) or "query".

Response:

{
  "ok": true,
  "fingerprint": "emb_5a3f19c407c1e2b8",
  "dimension": 1024,
  "embeddings": [{ "index": 0, "vector": [0.01, "…"] }],
  "usage": { "credits": 1 }
}

GET /embed — free key check

Same auth, no body, no metering. Returns { "ok": true, "fingerprint": "…", "dimension": 1024 } so a client can validate its key and pin the embedding space before the first paid call.

POST /rerank

{ "query": "where is auth checked?", "documents": ["…", "…"] }

query: non-empty string; documents: 1–1,000 non-empty strings; same 480,000-character total cap.

Response — rows in provider order, sort by score yourself:

{
  "ok": true,
  "results": [{ "index": 0, "relevanceScore": 0.87 }],
  "usage": { "credits": 1 }
}

GET /rerank is the matching free key check and returns { "ok": true }.

Billing

1 credit per started 1,000 upstream tokens. Rerank tokens meter into the same monthly counter as embeddings — see GET /usage.

Errors

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

Status	Code	Meaning
400	`INVALID_BODY`	Body failed validation.
401	`INVALID_API_KEY`	Missing, malformed or revoked key.
413	`INPUT_TOO_LARGE`	Over the 480k character cap.
429	`QUOTA_EXCEEDED`	Monthly quota exhausted.
502	`UPSTREAM_ERROR` / `UPSTREAM_UNREACHABLE`	Upstream rejected or unreachable.
503	`EMBED_UNAVAILABLE` / `RERANK_UNAVAILABLE`	Upstream not configured server-side.
504	`UPSTREAM_TIMEOUT`	Upstream took longer than 60 s.