Lexically query one subject's candidates
curl --request POST \
--url https://api.praxa.io/v1/memory/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"apiVersion": {},
"subject": "<string>",
"query": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({apiVersion: {}, subject: '<string>', query: '<string>'})
};
fetch('https://api.praxa.io/v1/memory/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.praxa.io/v1/memory/query"
payload = {
"apiVersion": {},
"subject": "<string>",
"query": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"apiVersion": "v1",
"retrievalMode": "lexical",
"data": [
{
"lexicalRank": 0,
"candidate": {
"id": "018f0000-0000-7000-8000-000000000001",
"state": "candidate",
"contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"createdAt": "2026-08-13T12:00:00.000Z",
"record": {
"apiVersion": "v1",
"providerId": "mem0",
"sourceId": "example",
"externalRecordId": "example",
"revision": "example",
"kind": "message",
"subject": "example",
"visibility": "subject",
"content": "example",
"provenance": "example",
"occurredAt": "example",
"observedAt": "example"
}
}
}
]
}
Memory candidates
Lexically query one subject's candidates
Run bounded lexical search over one subject’s isolated Praxa memory candidates with provider and record-kind filters.
POST
/
v1
/
memory
/
query
Lexically query one subject's candidates
curl --request POST \
--url https://api.praxa.io/v1/memory/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"apiVersion": {},
"subject": "<string>",
"query": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({apiVersion: {}, subject: '<string>', query: '<string>'})
};
fetch('https://api.praxa.io/v1/memory/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.praxa.io/v1/memory/query"
payload = {
"apiVersion": {},
"subject": "<string>",
"query": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"apiVersion": "v1",
"retrievalMode": "lexical",
"data": [
{
"lexicalRank": 0,
"candidate": {
"id": "018f0000-0000-7000-8000-000000000001",
"state": "candidate",
"contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"createdAt": "2026-08-13T12:00:00.000Z",
"record": {
"apiVersion": "v1",
"providerId": "mem0",
"sourceId": "example",
"externalRecordId": "example",
"revision": "example",
"kind": "message",
"subject": "example",
"visibility": "subject",
"content": "example",
"provenance": "example",
"occurredAt": "example",
"observedAt": "example"
}
}
}
]
}
Run bounded lexical search over one subject’s isolated Praxa memory candidates with provider and record-kind filters.
Availability: Qualification preview. Required scope:
memory:read.Authenticate safely
Create a disposable personal workspace API key with exactlymemory:read. Send it as Authorization: Bearer $PRAXA_API_KEY. A Gateway OAuth token, Supabase JWT, provider credential, or organization memory key is not interchangeable with this key.
The hosted playground sends the credential from your browser session to the documented API through the configured playground proxy. Use test data, never share the key, and revoke it when the check ends.
Request fields
v1
required
apiVersion request field.
string
required
subject request field.
string
required
query request field.
array<mem0 | zep | graphiti | langgraph | letta | openai_agents | custom>
providerIds request field.
array<message | fact | summary | episode | pinned_context | document | entity | edge>
kinds request field.
integer
limit request field.
Runnable request examples
curl --fail-with-body -X POST 'https://api.praxa.io/v1/memory/query' \
-H "Authorization: Bearer $PRAXA_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"apiVersion": "v1",
"subject": "customer-42",
"query": "weekly summaries",
"providerIds": [
"custom"
],
"kinds": [
"fact"
],
"limit": 20
}'
const response = await fetch("https://api.praxa.io/v1/memory/query", {
"method": "POST",
"headers": {
"Authorization": `Bearer ${process.env.PRAXA_API_KEY}`,
"Content-Type": "application/json"
},
"body": JSON.stringify({
"apiVersion": "v1",
"subject": "customer-42",
"query": "weekly summaries",
"providerIds": [
"custom"
],
"kinds": [
"fact"
],
"limit": 20
})
});
const text = await response.text();
if (!response.ok) throw new Error(`${response.status}: ${text}`);
console.log(text ? JSON.parse(text) : { status: response.status });
import json
import os
from urllib import error, request
payload = json.dumps({
"apiVersion": "v1",
"subject": "customer-42",
"query": "weekly summaries",
"providerIds": [
"custom"
],
"kinds": [
"fact"
],
"limit": 20
}).encode()
req = request.Request(
"https://api.praxa.io/v1/memory/query",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['PRAXA_API_KEY']}",
"Content-Type": "application/json"
},
data=payload,
)
try:
with request.urlopen(req, timeout=30) as response:
text = response.read().decode()
print(json.loads(text) if text else {"status": response.status})
except error.HTTPError as exc:
raise RuntimeError(f"{exc.code}: {exc.read().decode()}") from exc
What success means
A200 response contains subject-scoped lexical matches. It is not vector, semantic, or graph recall.
Successful response
200 — Bounded lexical matches for the requested subject.v1
required
apiVersion response field.
lexical
required
retrievalMode response field.
array<object>
required
data response field.
{
"apiVersion": "v1",
"retrievalMode": "lexical",
"data": [
{
"lexicalRank": 0,
"candidate": {
"id": "018f0000-0000-7000-8000-000000000001",
"state": "candidate",
"contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"createdAt": "2026-08-13T12:00:00.000Z",
"record": {
"apiVersion": "v1",
"providerId": "mem0",
"sourceId": "example",
"externalRecordId": "example",
"revision": "example",
"kind": "message",
"subject": "example",
"visibility": "subject",
"content": "example",
"provenance": "example",
"occurredAt": "example",
"observedAt": "example"
}
}
}
]
}
Handle failures
| Response | Meaning | Safe action |
|---|---|---|
400 invalid_request | The method, path, headers, query, or body failed strict validation. | Correct the request; do not retry unchanged input. |
401 authentication_failed | The bearer key is missing, malformed, expired, or revoked. | Stop and replace the key through the authenticated console. |
403 authorization_failed | The authenticated key lacks scope or tenant authority. | Request only the missing least-privilege scope; never substitute another tenant ID. |
429 rate_limited | The principal exceeded a bounded rate. | Honor retryAfterMs or Retry-After, add jitter, and cap attempts. |
retryable 5xx | The server could not confirm a final response. | Reconcile reads or replay the exact keyed mutation before creating new work. |
Example problem
{
"type": "https://docs.praxa.io/problems/authorization-failed",
"title": "Authorization failed",
"status": 403,
"code": "authorization_failed",
"detail": "The API key does not grant the required scope.",
"retryable": false
}
Verify the result
- Require
retrievalMode: "lexical". - Confirm every result matches the requested subject and filters.
- Query a second subject and tenant and require isolation.
Retry, cleanup, and production use
- Treat
401,403, and409as authority or state signals, not generic retry prompts. - For
429or retryable 5xx responses, follow server retry guidance and keep a bounded attempt budget. - Move the request into a trusted application backend before production; never ship the Praxa key in browser or mobile code.
- Revoke the disposable key, disable test webhooks, and erase disposable candidate data after validation.
Last modified on August 14, 2026