Skip to content
calternal docs

Restore only the exact saved-search file still held under its Trash receipt.

POST
/api/v1/search/saved/{id}/trash/undo
curl --request POST \
  --url https://example.com/api/v1/search/saved/example/trash/undo \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "expected_hash": "example", "trash_name": "example" }'

Route: /api/v1/search/saved/{id}/trash/undo. Inputs: id. Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Saved search id

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Trash Undo names one opaque entry and checks its bytes before restoring it.

object
expected_hash
required
string
trash_name
required
string
Examplegenerated
{
  "expected_hash": "example",
  "trash_name": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The same saved search restored from Trash

Media typeapplication/json

A saved search: a named query that works like a smart folder (DESIGN §32 S10). It is user data, stored as one JSON file per search in <home>/.calternal/saved-searches/<id>.json.

object
created
required

Creation time (RFC 3339, UTC).

string
id
required

Stable identifier (a lowercase UUID). Links use it, so a rename never breaks them.

string
name
required

Display name chosen by the user.

string
pinned
required

True when the search shows in the sidebar.

boolean
query
required

The raw query, operators included, exactly as the search field shows it.

string
updated
required

Last change time (RFC 3339, UTC).

string
Examplegenerated
{
  "created": "example",
  "id": "example",
  "name": "example",
  "pinned": true,
  "query": "example",
  "updated": "example"
}

400

Section titled “400”

Invalid Trash receipt

Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

404

Section titled “404”

The Trash entry does not belong to this saved search

Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”

The Trash entry changed or the ID is already in use

Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}