The API

The hosted API is the PRME HTTP API with an API key in front of it. This page covers what is different from the HTTP API reference, which describes running the server yourself.

Base URL and routes


https://api.prismemory.com

Every route in the PRME HTTP API reference is available, apart from the changes listed below. The full list of routes, with request and response shapes, is the service’s own interactive page at /docs. Its machine-readable form is /openapi.json. Neither needs a key.

GET /v1/health also needs no key. Every other route needs one.

Authentication

Send the key of one project as a bearer token:


Authorization: Bearer prm_live_<32 characters>

The service stores only a hash of the key and never logs it. A key works for one project only. Revoking a key, or deleting its project, stops it within a minute.

A refused key gets 401 and WWW-Authenticate: Bearer, with a reason_code:

`reason_code`	Meaning
`api_key_missing`	The request had no `Authorization` header.
`api_key_invalid`	The key is not one the service knows.
`api_key_revoked`	The key was revoked. Deleting a project revokes its keys.
`project_deleted`	The key belongs to a project that was deleted.

Who is `user_id`?

A key acts for the whole project. The user_id in a body or a query names one of your own end users. The engine does not check it, so a program that serves several end users must send the right one each time.

Error format

Errors that the hosted layer raises have this shape:


{ "detail": "Invalid or missing API key", "reason_code": "api_key_missing" }

Errors that the engine raises on its own routes keep the engine’s shape, { "detail": "..." }. Use reason_code when it is there, and the HTTP status when it is not. The Limits and errors page lists the codes.

Every response has an X-Request-ID header. Include it when you contact the maintainer about a request. The service chooses this id itself and does not use one that you send.

Changes from PRME

These requests are refused with 422 before they do any work. A refused request is not counted against your limits.

Request	`reason_code`	Why
`POST /v1/ingest` with `wait_for_extraction: true`	`wait_for_extraction_unsupported`	A waiting request would hold a project’s engine for minutes. An ingest answers once it is saved.
A `policy` on store or ingest, or any call of `POST /v1/privacy/policy`	`privacy_policy_unsupported`	The engine’s evidence privacy options are off in the alpha.
`POST /v1/reembed`	`reembed_unsupported`	The service uses one fixed embedding model.

To follow an ingest’s extraction, call GET /v1/events/{event_id}/extraction-status. It reports pending, running, complete, or failed. POST /v1/events/{event_id}/retry-extraction makes a failed or pending job due again. It counts as one ingest call.

Re-ingest runs in the background

POST /v1/reingest processes one user’s stored memories again, for example after an engine change, and replaces the claims derived from them. It never changes or deletes the original memories. The hosted service runs it as a background job, so the request answers at once:

Send {"user_id": "...", "dry_run": true}. The answer is a preview with counts and an estimated cost. Nothing is done or counted.
Send the same body with "dry_run": false. The answer is 202 with a run_id.
Read GET /v1/reingest/{run_id} until state is complete or failed. Once every five seconds is enough.

A run takes up to 500 memories by default. Each memory it takes is one ingest call. A second run for the same user while one is working is 409 with reason_code reingest_running.

Bounds on request size and work

The service holds a few parameters to a ceiling:

Where	Allowed	Error
`limit` on `GET /v1/nodes`	0 to 1,000	`422` `limit_out_of_range`
`budget_ms` on organize and the two process routes	0 to 30,000	`422` `budget_ms_out_of_range`
`jobs` on `POST /v1/organize`	at most 32 names	`422` `jobs_too_many`
`max_hops` on the neighborhood route	1 to 3	`422` `max_hops_out_of_range`
`direction` on the chain route	`forward` or `backward`	`422` `direction_invalid`
`limit` on `POST /v1/reingest`	1 to 20,000	`422` `limit_out_of_range`
Request body	256 KiB	`413` `body_too_large`
Request body of `POST /v1/ingest/fast` and the learning batch routes	4 MiB	`413` `body_too_large`
`content` of one store or ingest	32 KiB	`413` `content_too_large`

Retries

POST /v1/store and POST /v1/ingest are not safe to retry. A retry stores the text again.
POST /v1/ingest/fast with an Idempotency-Key is safe to retry. See the quick start.
A 503 with reason_code database_unavailable or lease_unavailable means the service was busy or a database was waking up. Wait a moment and send the request again.
A 429 with a Retry-After header means you hit the rate limit. Wait that many seconds.

What the service keeps

Your memory is kept in a private space for the project. Deleting a project revokes its keys within a minute. Its memory is scheduled for removal after seven days. In the alpha, the team runs that removal by hand, so it can take longer. To restore a project within the seven days, use the contact address on the privacy page .
Keys are stored only as a hash.
Logs have one line per request with the method, path, status, duration, and project. They never contain request or response bodies or keys. Your user_id is logged only as a hash.
Usage counts are kept per project and per day, as numbers. See Limits and errors.