# delete_row

Source: https://modulify.ai/docs/api/database/delete-row

Permanently deletes one row from a table in a site database, identified by its primary key.

- Title: Delete a row from a collection
- Scope: `data:write`
- Access: Destructive
- Endpoint: `POST /v1/delete_row`

The row is gone for good, with no undo. The tool tells the client to read it with `list_rows` first, tell you exactly what it is about to remove, and call this only once you have said yes.

A key matching no row is not an error: the call succeeds with `deleted` false, so read that field rather than the status. A row other collections point at either refuses to delete or, where the link cascades, takes those linked rows with it. The primary key column must be the table's own single-column primary key, so a call never deletes more than one row.

Files the row uses from the `CMS` folder of storage are deleted with it, unless another row of the same collection still uses them. See [Duplicate, export or delete an item](https://modulify.ai/docs/data/cms#duplicate-export-or-delete-an-item).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/delete_row`, sending the inputs below as a JSON object. The token needs the `data:write` 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/delete_row \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","name":"NAME","primaryKeyValue":"PRIMARY_KEY_VALUE"}'
```

Over MCP, the same method is the [delete_row tool](https://modulify.ai/docs/mcp/database/delete-row).

## 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 name. |
| `primaryKeyValue` | string | Yes | The primary key value of the row to delete. |
| `primaryKeyColumn` | string | No | The primary key column, when it is not the default `id`. It must be the table's own single-column primary key, so it never matches more than one row. |

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