> ## Documentation Index
> Fetch the complete documentation index at: https://docs.urbackend.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Document

> 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 <accessToken>`.

### Path parameters

<ParamField path="collectionName" type="string" required>
  The name of the collection containing the document.
</ParamField>

<ParamField path="id" type="string" required>
  The MongoDB ObjectId string of the document to delete.
</ParamField>

### Query parameters

<ParamField query="permanent" type="boolean" default="false">
  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.
</ParamField>

### 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

<ResponseField name="success" type="boolean">
  `true` when the document was moved to trash.
</ResponseField>

<ResponseField name="data" type="object">
  Object containing the `id` of the deleted document.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation message. `"Document moved to trash"` for soft deletes, `"Document permanently deleted"` when `permanent=true`.
</ResponseField>

### Code examples

<CodeGroup>
  ```javascript fetch (sk_live) theme={null}
  const docId = '64fd1234abcd5678ef901234';

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

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

  ```javascript fetch (pk_live + RLS) theme={null}
  const docId = '64fd1234abcd5678ef901234';

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

  ```bash curl theme={null}
  curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234" \
    -H "x-api-key: sk_live_YOUR_SECRET_KEY"
  ```

  ```bash curl (permanent) theme={null}
  curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef901234?permanent=true" \
    -H "x-api-key: sk_live_YOUR_SECRET_KEY"
  ```
</CodeGroup>

### Success response

```json theme={null}
{
  "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                             |


## Related topics

- [Database](/guides/database.md)
- [August 2026](/changelog/august-2026.md)
- [Delete File](/api-reference/storage/delete.md)
- [Row-Level Security](/concepts/row-level-security.md)