delete.mdx

title	Delete Document
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 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 <accessToken>.

Path parameters

The name of the collection containing the document. 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.

Response fields

`true` when the document was moved to trash. Object containing the `id` of the deleted document. Human-readable confirmation message. `"Document moved to trash"` for soft deletes, `"Document permanently deleted"` when `permanent=true`.

Code examples

const docId = '64fd1234abcd5678ef901234';

const res = await fetch(
  `https://api.urbackend.in/api/data/posts/${docId}`,
  {
    method: 'DELETE',
    headers: {
      'x-api-key': 'sk_live_YOUR_SECRET_KEY'
    }
  }
);

const { success, data, message } = await res.json();

const docId = '64fd1234abcd5678ef901234';

const res = await fetch(
  `https://api.urbackend.in/api/data/posts/${docId}`,
  {
    method: 'DELETE',
    headers: {
      'x-api-key': 'pk_live_YOUR_KEY',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

curl -X DELETE "https://api.urbackend.in/api/data/posts/64fd1234abcd5678ef901234" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

curl -X DELETE "https://api.urbackend.in/api/data/posts/64fd1234abcd5678ef901234?permanent=true" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

Success response

{
  "success": true,
  "data": {
    "id": "64fd1234abcd5678ef901234"
  },
  "message": "Document moved to trash"
}

With permanent=true, the message is "Document permanently deleted" instead.

Errors

Status	Cause
401 Unauthorized	Missing/invalid API key, or missing Bearer token on an RLS-enabled collection
403 Forbidden	pk_live without RLS, or the authenticated user doesn't own the document
404 Not Found	No document with that ID exists in the collection