Breadcrumbs

Delete and restore a document

Deleting a document does one of two things, and you choose which: it either moves the document to the trash, where it stays readable and can be brought back, or removes it outright. This guide walks both paths in four calls.

Before you begin

  • A document you no longer need. The examples work on a draft agreement that was never sent.

Step 1: Move the document to the trash

A plain delete is the reversible one:

DELETE /documents/pXq4NcYBhK9tWdA2mFzR
Authorization: Bearer YOUR_API_KEY

HTTP/2 204

Nothing comes back but the status: the document has been moved to the trash. It keeps its identifier, its content and its folder placements, and it stops appearing among your active documents.

Step 2: Read the trashed document

A document in the trash is still there to be read:

GET /documents/pXq4NcYBhK9tWdA2mFzR
Authorization: Bearer YOUR_API_KEY

HTTP/2 200

{
    "id": "pXq4NcYBhK9tWdA2mFzR",
    "title": "Employment Agreement (draft)",
    "trashed": true,
    ...
}

The read works exactly as before and trashed tells you the state, so your integration never has to remember what it threw away.

Tip

To enumerate the trash rather than check one document, search with trashed: GET /documents?trashed=true returns what is in it, while an ordinary search returns only active documents.

Step 3: Restore the document

Restoring takes the document out of the trash:

POST /documents/pXq4NcYBhK9tWdA2mFzR/restore
Authorization: Bearer YOUR_API_KEY

HTTP/2 204

The document is active again, with its title, content and folder placements as they were.

Step 4: Delete the document for good

Set permanent to remove the document instead of trashing it:

DELETE /documents/pXq4NcYBhK9tWdA2mFzR?permanent=true
Authorization: Bearer YOUR_API_KEY

HTTP/2 204

The document is gone: reading it — or trying to restore it — now answers 404. The same call works on a document that is already in the trash, so emptying something out of it takes one request, not a restore followed by a delete.

Caution

A permanent delete cannot be undone: the document does not reach the trash and there is nothing left to restore. Reach for it only when you are certain, and prefer the plain delete everywhere else.

Folders work the same way, with one difference: a folder takes everything nested inside it along, into the trash and back out of it again — Organize documents in folders covers that.

Complete example

Emptying a draft into the trash and, once your own retention rules say so, removing it for good — as a Node.js script. Error handling is minimal for brevity — in production, inspect the error envelope of non-2xx responses.

JavaScript
const BASE_URL = "https://sandbox.circularo.com/api/v1/public"; // your instance's base URL
const API_KEY = "YOUR_API_KEY";
const AUTH_HEADER = { "Authorization": `Bearer ${API_KEY}` };
const documentId = "pXq4NcYBhK9tWdA2mFzR"; // the document to discard

const trash = await fetch(`${BASE_URL}/documents/${documentId}`, { method: "DELETE", headers: AUTH_HEADER });
if (!trash.ok) throw new Error(`Delete failed: ${trash.status}`); // error handling kept minimal for brevity

// later, after whatever period your retention rules require
const document = await (await fetch(`${BASE_URL}/documents/${documentId}`, { headers: AUTH_HEADER })).json();
if (document.trashed) {
    await fetch(`${BASE_URL}/documents/${documentId}?permanent=true`, { method: "DELETE", headers: AUTH_HEADER });
    console.log(`Document ${documentId} removed for good`);
}

Next steps