Skip to content

Forget

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

Needs memories:forget, which reaches only what the acting user wrote. memories:forget-others reaches what others wrote too, by memory_ids, source or author, whether or not the acting user can see it; each such forget is recorded and shown to the author. what always reaches only the acting user’s own writing. What a forget reaches leaves recall at once, with every memory made from it, and can be brought back until the undo window closes. It answers the same whether or not anything matched. A forget by memory_ids or source takes the memories named and what was made from them, and nothing else: the same number or fact in another memory stays until that memory is forgotten too, as does the reply to a forgotten message unless it is named too. A memory another forget has already taken is passed over: if that forget is undone, the memory comes back, and this one does not hold it. A space holds at most 5,000 forgets open at once, counting forgets that matched nothing: a forget past that answers 429 open-forgets and changes nothing, for at most 30 days, until the earliest open forget’s undo window ends. frees_at gives that time. Undoing a forget frees a place at once. A forget sent again under an Idempotency-Key already honoured is answered as before and is not counted. One whose forget was undone answers 409 forget-undone with that forget, and takes nothing. Reading or undoing a forget is never refused for it. The body may be up to 16,384 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.

idempotency-key
string
/^[\x21-\x7e]{1,255}$/

1 to 255 visible ASCII characters, such as a UUID. A forget sent again in the same space with the same key and the same memories is the same forget: it takes nothing more and answers where the first one stands now, under its ID, for as long as the space is kept. If that forget was undone, it answers 409 forget-undone and takes nothing: send a new key to forget again. The same key with other memories is another forget. Without it, each forget sent is a new one, so a forget sent again after its answer was lost has another ID, and only the first can undo what was taken.

Media typeapplication/json
Any of:
object
what
required

In the user’s own words, such as my phone number.

string
>= 1 characters <= 1000 characters

The forget is under way.

Media typeapplication/json
object
id
required
string
/^[0-9a-f]{32}$/
state
required

Where what this forget took stands. open: gone from recall, and can be undone until undo_until. undone: brought back. closed: the undo window has closed and nothing of it can be read. erased: every key that could open a copy of it is destroyed too.

string
undo_until
required
string | null format: date-time
erased_at
required

When every key that could open a copy is, or will be, destroyed.

string | null format: date-time

Example

{
"id": "b7e04c2a9d3f18e6c5a0f29d4b81e7c3",
"undo_until": "2027-01-31T09:30:00Z",
"erased_at": "2027-01-31T09:30:00Z"
}

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"
}
}

forget-undone: the forget was sent again under an Idempotency-Key whose forget was undone. Nothing was taken. forget is that forget. Send a new key to forget again. user-erased: the acting user was erased after the request was let in. Nothing was taken.

Media typeapplication/json
Any of:
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
forget
required
object
id
required
string
/^[0-9a-f]{32}$/
state
required

Where what this forget took stands. open: gone from recall, and can be undone until undo_until. undone: brought back. closed: the undo window has closed and nothing of it can be read. erased: every key that could open a copy of it is destroyed too.

string
undo_until
required
string | null format: date-time
erased_at
required

When every key that could open a copy is, or will be, destroyed.

string | null format: date-time

Example

{
"forget": {
"id": "b7e04c2a9d3f18e6c5a0f29d4b81e7c3",
"undo_until": "2027-01-31T09:30:00Z",
"erased_at": "2027-01-31T09:30:00Z"
}
}

The request body is longer than 16,384 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"
}
}

rate-limited: 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. open-forgets: the space holds 5,000 forgets open, and frees_at says when a place frees. It sends no Retry-After.

Media typeapplication/json
Any of:
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
frees_at
required

When the earliest open forget’s undo window ends, which frees a place. Undoing a forget frees one at once.

string format: date-time

Example

{
"frees_at": "2027-01-31T09:30:00Z"
}

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 for this space 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"
}
}