From 5d843997186196ef4f611a56275c426830bd895d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 4 Sep 2026 05:13:02 +0000 Subject: [PATCH] docs: document permanent deletion via REST API and SDKs --- mintlify/docs/api-reference/data/delete.mdx | 19 ++++++++- mintlify/docs/guides/database.mdx | 47 ++++++++++++++++++--- mintlify/docs/sdk/database.mdx | 26 +++++++++++- 3 files changed, 81 insertions(+), 11 deletions(-) diff --git a/mintlify/docs/api-reference/data/delete.mdx b/mintlify/docs/api-reference/data/delete.mdx index 38a78a908..e7d970eb2 100644 --- a/mintlify/docs/api-reference/data/delete.mdx +++ b/mintlify/docs/api-reference/data/delete.mdx @@ -1,12 +1,14 @@ --- title: "Delete Document" -description: "Soft delete a document from a collection by its ID. Moves it to the trash." +description: "Delete a document from a collection by its ID. Soft deletes to the trash by default, or permanently with permanent=true." --- ## DELETE `/api/data/:collectionName/:id` Moves the document with the given ID to the trash by setting `isDeleted: true` and recording the `deletedAt` timestamp. The document remains recoverable for a **30-day grace period**, after which it is permanently deleted by a background cleanup worker. See the [Database Guide](/guides/database#soft-delete-trash) for more details. +Pass `permanent=true` to skip the trash and remove the document immediately. Permanent deletion cannot be undone. + ### Required header `x-api-key`: `sk_live_…` by default. `pk_live_…` is accepted only when the collection has **RLS enabled** and the request includes `Authorization: Bearer `. @@ -21,6 +23,12 @@ Moves the document with the given ID to the trash by setting `isDeleted: true` a The MongoDB ObjectId string of the document to delete. +### Query parameters + + + When `true`, deletes the document immediately instead of moving it to the trash. The document cannot be recovered, and its size is subtracted from your `databaseUsed` quota right away. When omitted or `false`, the document is soft deleted and quota is only reclaimed after the 30-day cleanup. + + ### RLS ownership check When using `pk_live` with RLS enabled, urBackend compares the existing document's owner field against the authenticated user's ID. You can only delete your own documents; attempting to delete another user's document returns `403`. @@ -36,7 +44,7 @@ When using `pk_live` with RLS enabled, urBackend compares the existing document' - Human-readable confirmation message. + Human-readable confirmation message. `"Document moved to trash"` for soft deletes, `"Document permanently deleted"` when `permanent=true`. ### Code examples @@ -79,6 +87,11 @@ curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef90123 -H "x-api-key: sk_live_YOUR_SECRET_KEY" ``` +```bash curl (permanent) +curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234?permanent=true" \ + -H "x-api-key: sk_live_YOUR_SECRET_KEY" +``` + ### Success response @@ -93,6 +106,8 @@ curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef90123 } ``` +With `permanent=true`, the message is `"Document permanently deleted"` instead. + ### Errors | Status | Cause | diff --git a/mintlify/docs/guides/database.mdx b/mintlify/docs/guides/database.mdx index 9f1462625..e4db9151e 100644 --- a/mintlify/docs/guides/database.mdx +++ b/mintlify/docs/guides/database.mdx @@ -167,7 +167,13 @@ const res = await fetch(`https://api.ub.bitbros.in/api/data/posts/${postId}`, { ## Soft delete and trash -When you delete a document using `DELETE /api/data/:collectionName/:id`, your backend moves it to the trash instead of removing it immediately. +When you delete a document using `DELETE /api/data/:collectionName/:id`, your backend moves it to the trash instead of removing it immediately. + +```bash +curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234" \ + -H "x-api-key: sk_live_YOUR_KEY" +``` + - Documents enter a **30-day grace period** before permanent deletion. - You can view trashed documents by appending the `include_deleted=true` query parameter to your read or aggregation requests. @@ -176,17 +182,44 @@ When you delete a document using `DELETE /api/data/:collectionName/:id`, your ba ### Permanent deletion -You can skip the grace period from the dashboard. On the **Database** page, enable the trash view, then click the delete icon on a trashed document. urBackend asks for confirmation, removes the document immediately, and reclaims its `databaseUsed` quota right away. +You can skip the grace period from the dashboard, the REST API, or the SDKs. Permanent deletion removes the document immediately and cannot be undone. - - For soft-deleted documents, your `databaseUsed` quota is only reclaimed after the 30-day period when the cleanup worker permanently deletes the expired documents. Permanent deletion reclaims quota immediately. - +**Dashboard:** on the **Database** page, enable the trash view, then click the delete icon on a trashed document. urBackend asks for confirmation, removes the document immediately, and reclaims its `databaseUsed` quota right away. -```bash -curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234" \ +**REST API:** append the `permanent=true` query parameter to the delete endpoint. urBackend responds with the message `"Document permanently deleted"` instead of `"Document moved to trash"`. + + + +```bash curl +curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234?permanent=true" \ -H "x-api-key: sk_live_YOUR_KEY" ``` +```typescript TypeScript SDK +await client.db.delete('posts', postId, { permanent: true }); + +// With an RLS token +await client.db.delete('posts', postId, { + token: accessToken, + permanent: true +}); +``` + +```python Python SDK +client.db.delete("posts", post_id, permanent=True) + +# With an RLS token +client.db.delete("posts", post_id, + token=client.auth.get_token(), + permanent=True) +``` + + + + + For soft-deleted documents, your `databaseUsed` quota is only reclaimed after the 30-day period when the cleanup worker permanently deletes the expired documents. Permanent deletion reclaims quota immediately. + + ## Schema validation If you define a schema for a collection in the dashboard, urBackend enforces it on every `POST` and `PUT` request. Supported field types include: diff --git a/mintlify/docs/sdk/database.mdx b/mintlify/docs/sdk/database.mdx index 5f532233c..f3709c49a 100644 --- a/mintlify/docs/sdk/database.mdx +++ b/mintlify/docs/sdk/database.mdx @@ -122,10 +122,32 @@ await client.db.patch('products', 'id_123', { price: 45 }); ## delete -Delete a document by its ID. +Delete a document by its ID. By default the document is soft deleted and moved to the trash, where it stays recoverable for 30 days. Pass `permanent: true` to delete it immediately and reclaim its storage quota right away. Permanent deletion cannot be undone. ```typescript -delete(collection: string, id: string, token?: string): Promise<{ deleted: boolean }> +delete(collection: string, id: string, options?: { token?: string, permanent?: boolean } | string): Promise<{ deleted: boolean }> +``` + +**Options** + +| Option | Type | Description | +|---|---|---| +| `token` | `string` | Bearer token for the RLS ownership check. | +| `permanent` | `boolean` | When `true`, permanently deletes the document instead of moving it to the trash. Defaults to `false`. | + +Passing a token string as the third argument is still supported for backward compatibility: `delete('posts', id, accessToken)`. + +**Example** + +```typescript +// Soft delete (moves to trash, recoverable for 30 days) +await client.db.delete('posts', 'id_123'); + +// Permanent delete with an RLS token +await client.db.delete('posts', 'id_123', { + token: accessToken, + permanent: true +}); ``` ---