> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted candidate API

> Review the deployed /v1/memory candidate-plane routes and their pending authenticated qualification.

<Warning>
  These routes are a deployed qualification preview. Route smoke tests and
  fail-closed unauthenticated `401` responses are proven. Authenticated positive,
  wrong-scope, revoked-key, cross-tenant, idempotency, export, and deletion
  canaries remain pending; a `401` proves only the shared gateway authentication
  boundary, not authorized record behavior.
</Warning>

## Candidate routes

| Method   | Route                           | Scope          | Intended result                                                                         |
| -------- | ------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `POST`   | `/v1/memory/records`            | `memory:write` | Create or replay one bounded candidate record under the authenticated tenant.           |
| `POST`   | `/v1/memory/query`              | `memory:read`  | Query candidates with an explicit `retrievalMode: "lexical"` in the first hosted slice. |
| `GET`    | `/v1/memory/export`             | `memory:read`  | Export bounded NDJSON pages and follow `X-Praxa-Next-Cursor` when present.              |
| `DELETE` | `/v1/memory/records/{recordId}` | `memory:write` | Hard-erase candidate payload content and return a content-free deletion receipt.        |

Existing Platform keys gain no memory scope automatically. The key principal selects the tenant;
the request body cannot provide tenant, actor, organization, or Praxa user authority.

## Try the frozen request contract

The portable-envelope schema is frozen and aligned across the runtime and the
published `@praxa/sdk/memory` package. The [API Playground](/api-playground/overview)
now generates requests from that OpenAPI document, and the [hosted-memory
tutorial](/tutorials/hosted-memory-candidates) walks through create, lexical
query, NDJSON export, and hard erasure.

Use disposable content and a least-privilege personal-workspace key while the
authenticated qualification matrix remains pending. The presence of a request
example does not promote this plane from qualification preview.

The stable boundary is already explicit:

* records remain isolated candidates;
* hosted provider IDs are `mem0`, `zep`, `graphiti`, `langgraph`, `letta`, `openai_agents`, and
  `custom`;
* durable candidate kinds are exactly `message`, `fact`, `summary`, `episode`, `pinned_context`,
  `document`, `entity`, and `edge`; LangGraph checkpoints are rejected rather than converted;
* provenance names an `explicit`, `observed`, `inferred`, or `imported` origin, confidence from
  `0` to `1`, a capture time, and bounded evidence IDs;
* lexical retrieval is labelled lexical;
* provider identity, external ID, revision, record kind, provenance, visibility, and timestamps
  survive round trips;
* retries bind an idempotency key to the same request digest;
* all-provider failure is not an empty result;
* deletion leaves no candidate content in its receipt;
* no route promotes data into Praxa personal memory or AHCE.

Deleting a candidate does not delete the provider-owned source record. Perform
provider deletion through that provider's own authenticated API when your data
policy requires both copies to be erased.

## Separate memory planes

`POST /v8/memory/query` is an OAuth Integration Gateway contract for purpose- and
compartment-scoped retrieval. It neither manages provider connections nor aliases this `/v1`
candidate plane. See [Query Memory](/api-reference/memory/query) for that separate contract.