The trash

What was deleted, restoring it and deleting it for good.

GET /v1/trash

The items in the trash, newest first.

Deleted templates, folders and libraries, kept for trash.retentionDays (default 30; 0 keeps them until purged). Needs template.read.

Parameters

Name	In	Type	Required	Description
kind	query	template, folder, library

Responses

Status	Description	Body
200		object
400	An unknown kind
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

200 body (application/json)

Field	Type	Required	Description
items	array of TrashItem
retentionDays	integer

DELETE /v1/trash

Empty the trash.

Purges every item but the libraries that published reports still pin, which it keeps and counts in kept. Needs trash.purge, which agent keys never have. Audited as trash.empty with the number of items purged.

Responses

Status	Description	Body
200
403	The caller lacks trash.purge
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

GET /v1/trash/{item}

One item in the trash.

Needs template.read.

Parameters

Name	In	Type	Required	Description
item	path	string	yes	A trash item's id, t_<hex>

Responses

Status	Description	Body
200	The item	TrashItem
404	No such item
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

DELETE /v1/trash/{item}

Delete an item for good.

Removes the item and everything it holds from the template store or dataDir. Git history isn't rewritten: the commits from before the trash keep the published versions (docs/operations/trash.md says how to erase them by hand). A library is removed from every environment branch, releases and all, and is refused with 409 library-in-use while a published report pins one of its releases. Needs trash.purge, which agent keys never have. Audited as <kind>.purge.

Parameters

Name	In	Type	Required	Description
item	path	string	yes	A trash item's id, t_<hex>

Responses

Status	Description	Body
200
403	The caller lacks trash.purge
404	No such item
409	Published reports still pin releases of the library	object
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/trash/{item}/restore

Restore an item.

Needs what deleting it needed: template.write in every environment for an item that holds templates, library.write in every environment for a library, template.write otherwise. A library's marker goes and its draft comes back on each branch, with a commit "restore library <name>". Each template's trees go back with a commit "restore <id>" on the branches that had it, with its draft, edit log, history and conversations; its folders are made again. A folder item restores whole or not at all. Cancelled jobs and withdrawn approvals stay that way. Audited as <kind>.restore.

Parameters

Name	In	Type	Required	Description
item	path	string	yes	A trash item's id, t_<hex>

Responses

Status	Description	Body
200		object
403	The caller couldn't have deleted it
404	No such item
409	Something with the item's name has been made since
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

200 body (application/json)

Field	Type	Required	Description
id	string
status	restored
item	TrashItem