Skip to content
Kindgi

Retrieve facts by intent

POST
/v1/memory/retrieve
curl --request POST \
  --url https://example.com/v1/memory/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "mode": "list", "query": "example", "type": "example", "scope": { "tenantId": "example", "userId": "example", "orgId": "example", "projectId": "example", "threadId": "example", "sessionId": "example" }, "limit": 1, "embeddingModel": "example" }'

Cross-history retrieval. Body is a RetrieveIntent shape mirroring the agent-side declarative retrieval. Semantic modes require an embedding provider bound on the deployment.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Retrieval intent — mirrors RetrievalIntent from @kindgi/agents, widened for direct-HTTP use. mode: "list" returns a plain scoped list (no query). mode: "keyword" runs full-text search. mode: "semantic" runs vector similarity search — requires an embedding provider bound on the deployment; if unavailable, the route returns 400 bad-input. mode: "both" unions keyword + semantic results, dedup by fact id.

object
mode
required
string
Allowed values: list keyword semantic both
query

Required for keyword / semantic / both; ignored for list.

string
type
string
>= 1 characters
scope

Fact scope object. tenantId is required; every optional key narrows the fact (userId, orgId, projectId, threadId, sessionId). Additional keys accepted for forward compatibility.

object
tenantId
required
string
userId
string
orgId
string
projectId
string
threadId
string
sessionId
string
key
additional properties
any
limit
integer
>= 1
embeddingModel
string

Responses

Section titled “Responses”

200

Section titled “200”

Retrieval results.

Media typeapplication/json
object
results
required
Array<object>
object
fact
required
object
id
required

FactId.

string
type
required

Fact type identifier (pack-defined; a few are framework-standard).

string
scope
required

Fact scope object. tenantId is required; every optional key narrows the fact (userId, orgId, projectId, threadId, sessionId). Additional keys accepted for forward compatibility.

object
tenantId
required
string
userId
string
orgId
string
projectId
string
threadId
string
sessionId
string
key
additional properties
any
version
required

Monotonic version within (scope, id). Supersession increments.

integer
>= 1
createdAt
required
string format: date-time
updatedAt
string format: date-time
content

Free-form structured payload.

contentRef

blob://<provider>/<bucket>/<key> when the payload is stored externally.

string
contentHash
string
size
integer
embeddingModel
string
retention
object
keepUntil
string format: date-time
keepDays
integer
>= 1
legalHold
boolean
source
object
kind
required
string
Allowed values: http-api blob mcp-tool external-db user-input
uri
string
freshness
required
object
ttlSeconds
integer
lastVerifiedAt
string format: date-time
etag
string
sourceVersion
string
refresh
required
object
strategy
required
string
Allowed values: on-read background manual
handler
string
priority
integer
causedByLogId
Array<string>
supersedes

FactId of the predecessor when this row supersedes another.

string
score

Relevance score. Keyword mode returns an implementation-defined rank (higher = better). Semantic mode returns cosine similarity in [-1, 1] (higher = better). Absent for list mode.

number
Example
{
  "results": [
    {
      "fact": {
        "source": {
          "kind": "http-api",
          "refresh": {
            "strategy": "on-read"
          }
        }
      }
    }
  ]
}

400

Section titled “400”

Malformed intent, or semantic mode requested and no embedding provider is bound.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body, or resource-state conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}