Skip to main content
POST
memory.items.search

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
scope
object
required

The memory set and optional end-user, agent or session within it.

query
string
required

The facts to find.

Required string length: 1 - 2000
filters
object

A filter tree, at most three levels deep. Ownership is always enforced separately.

fields
enum<string>[]

Extra fields to return. Text and reference are always returned.

Maximum array length: 12
Available options:
metadata,
categories,
createdAt,
updatedAt,
expirationDate,
user,
agent,
run,
structuredAttributes,
synthesized,
lifecycleState
limit
integer
default:10

How many owned rows to return, at most 50.

Required range: 1 <= x <= 50
cursor
string

Opaque nextCursor from the same query.

Required string length: 1 - 200
showExpired
boolean
default:false

Include memories whose expiration date has passed.

startDate
string<date>

Only memories created on or after this date.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
endDate
string<date>

Only memories created on or before this date.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
categories
string[]

Category names to match.

Maximum array length: 50
Required string length: 1 - 100
keywords
string

Words to match in memory text.

Required string length: 1 - 1000
threshold
number

Minimum relevance.

Required range: 0 <= x <= 1
rerank
boolean
default:false

Reorder results by relevance.

Use legacy keyword matching where supported.

metadataOnly
boolean
default:false

Use only metadata-based matching where supported.

filterResults
boolean
default:false

Apply legacy result filtering where supported.

referenceDate
string<date>

Date for temporal queries.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$

Response

The result

results
object[]
required

The matching items.

nextCursor
string

Pass as cursor to get the next page; absent on the last page.