Skip to content

Recall

POST
/v1/spaces/{space_id}/recall
curl --request POST \
--url https://api.metaphoric.io/v1/spaces/personal/recall \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'metaphor-user: customer-4821' \
--data '{ "question": "example", "budget": 2000 }'

Needs memories:read. The context for a question from one space. Recall never returns a memory the user cannot see, or anything made from one. The body may be up to 65,536 bytes.

space_id
required

personal for the acting user’s own space, or a shared space’s ID: 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. personal always answers: before the user’s first write it holds nothing.

string
/^[a-z0-9][a-z0-9-]{0,62}$/

Example

personal

personal for the acting user’s own space, or a shared space’s ID: 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. personal always answers: before the user’s first write it holds nothing.

metaphor-user

A member’s ID, which Metaphor issued and which starts with metaphor:, or your own ID for an end user: 1 to 256 visible ASCII characters but " and \, not starting with metaphor:. Metaphor keeps an end user’s ID as you send it only on a key held to that user. A service user’s ID is issued by Metaphor, so it starts with metaphor: too.

string
>= 1 characters <= 256 characters /^[!#-[\]-~]+$/

Example

customer-4821

The user this request acts for. Required for a key of your own server; a key held to a user may leave it out, or send that user’s ID. A server key acts for a member only where the owner turned that on for the project, and each such request is recorded.

Media typeapplication/json
object
question
required

The question, in the user’s words. It is never written to a log.

string
>= 1 characters <= 4000 characters
budget

The most tokens the answer’s lines may take together.

integer
default: 2000 >= 100 <= 10000

The lines, in the order they are best read. None when nothing in the space answers the question.

Media typeapplication/json
object
items
required
Array<object>
object
text
required
string
heading
required
string | null
occurred_at
required

When it happened, if known.

string | null format: date-time
memory_ids
required

Up to 20 of the memories this line was made from, each one a memory the user can see. The newest come first, by the minute each was written. Memories written in the same minute come in order of ID, not the order they were written.

Array<string>
<= 20 items

Example

{
"items": [
{
"occurred_at": "2027-01-31T09:30:00Z",
"memory_ids": [
"4f1c9a7e2b8d06c3a5e9f17b20d4c8e6"
]
}
]
}

The request is not valid, or names no user to act for.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

No valid API key was sent.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key does not allow this, or not for this user.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

No such shared space.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

user-erased: the acting user was erased after the request was let in. Nothing was done.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request body is longer than 65,536 bytes.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The body was not sent as application/json.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key sent more than 600 requests in a minute, the user’s keys together more than 2000, or the tenant’s keys together more than 6000. Wait the seconds Retry-After gives.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

Something went wrong. Try again.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request could not be checked, or the tenant is not set up to recall yet. Try again later.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}