# clear_collection

Source: https://modulify.ai/docs/api/database/clear-collection

Deletes every row in one table of a site database in a single irreversible step, keeping the table and its columns.

- Title: Delete every row in a collection
- Scope: `sites:delete`
- Access: Destructive
- Endpoint: `POST /v1/clear_collection`

Nothing can restore the rows it deletes, and the live site loses that content the moment it runs. The table and its columns survive, so only the content goes, and the table's files in the `CMS` folder of storage are deleted with its rows. The response counts the deleted rows in `cleared`.

While other collections still link to those rows it is refused with a `409` and `Some items are linked from other collections and cannot be cleared. Clear those collections first!` Where those links cascade, the linked rows in the other collections go too. The field metadata table and the join tables behind multi-reference fields cannot be cleared this way.

It needs the **Delete projects** permission in the workspace, which the stock member role does not hold. That makes it stricter than deleting a site, because a member may delete a site they created but may not empty its collections.

Before it runs, the tool tells the client to read `eligibility` from `list_database_backups`. While that reads `ready` and `canBackup` is true, the client takes a backup with `create_database_backup`, when it has that tool, and waits until the backup reads `ready`. On `unsupported` or `no-database`, no backup of these rows exists or ever will, and a database backup can only ever be downloaded from the editor, never restored.

The tool tells the client never to call it to tidy up, to retry a failed import or because a collection looks unused, and to call it only when you asked for that exact collection to be emptied and confirmed after the client named it back to you. See [Clear one collection's data](https://modulify.ai/docs/data/clearing-and-exporting#clear-one-collections-data).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/clear_collection`, sending the inputs below as a JSON object. The token needs the `sites:delete` scope.

> **Warning**
>
> This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it.

```bash
curl -X POST https://api.modulify.ai/v1/clear_collection \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","name":"NAME"}'
```

Over MCP, the same method is the [clear_collection tool](https://modulify.ai/docs/mcp/database/clear-collection).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |
| `schema` | string | No | The schema the collection lives in, exactly as `list_collections` reports it. Leave it out to use the site database's own default, which is right unless `list_collections` showed something else. A site on the newer database always uses its default. |
| `name` | string | Yes | The table to empty, exactly as `list_collections` reports it. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.