post_api_memories_explain

POST

/api/memories/explain

curl --request POST \
  --url https://example.com/api/memories/explain \
  --header 'Content-Type: application/json' \
  --data '{ "limit": 1, "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "prompt": "example" }'

Request Body^required

Media typeapplication/json

object

limit

integer | null format: int64

profile_id

string | null format: uuid

project_id

string | null format: uuid

prompt

required

string

Example^generated

{
  "limit": 1,
  "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "prompt": "example"
}

Responses

200

Memory retrieval score explanation for a prompt

Media typeapplication/json

object

profile_id

string | null format: uuid

prompt

required

string

rows

required

Array<object>

object

entity

required

number format: double

importance

required

number format: double

lexical

required

number format: double

memory

required

object

archived_at

string | null format: date-time

created_at

required

string format: date-time

id

required

string format: uuid

importance

required

number format: double

last_used_at

string | null format: date-time

memory_kind

required

string

pinned

required

boolean

project_id

string | null format: uuid

salience

required

number format: double

scope

required

string

source_id

string | null format: uuid

source_type

required

string

superseded_by

string | null format: uuid

text

required

string

updated_at

required

string format: date-time

user_id

string | null format: uuid

version

required

integer format: int32

workspace_id

required

string format: uuid

pinned_boost

required

number format: double

recency

required

number format: double

salience

required

number format: double

scope_match

required

number format: double

score

required

number format: double

semantic

required

number format: double

visible_reason

required

string

Example^generated

{
  "profile_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "prompt": "example",
  "rows": [
    {
      "entity": 1,
      "importance": 1,
      "lexical": 1,
      "memory": {
        "archived_at": "2026-04-15T12:00:00Z",
        "created_at": "2026-04-15T12:00:00Z",
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "importance": 1,
        "last_used_at": "2026-04-15T12:00:00Z",
        "memory_kind": "example",
        "pinned": true,
        "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "salience": 1,
        "scope": "example",
        "source_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "source_type": "example",
        "superseded_by": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "text": "example",
        "updated_at": "2026-04-15T12:00:00Z",
        "user_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "version": 1,
        "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
      },
      "pinned_boost": 1,
      "recency": 1,
      "salience": 1,
      "scope_match": 1,
      "score": 1,
      "semantic": 1,
      "visible_reason": "example"
    }
  ]
}

400

Structured client error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}