Projects

Copy page

Deleting Projects & Sheets

Remove projects and sheets you no longer need — one at a time, or many in a single call.

Deleting a project or sheet removes it — it is no longer returned by or accessible through the API.

Endpoints

Code
 
DELETE /v1/projects/{projectId}    → delete one project
POST   /v1/projects/bulk-delete    → delete up to 100 projects
DELETE /v1/sheets/{sheetId}        → delete one sheet
POST   /v1/sheets/bulk-delete      → delete up to 100 sheets

Delete Project → · Bulk Delete Projects → · Delete Sheet → · Bulk Delete Sheets →

Deleting one resource

A DELETE returns 204 No Content on success:

Code
 
curl -X DELETE "https://api.calcs.com/v1/projects/{projectId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → 204 No Content

curl -X DELETE "https://api.calcs.com/v1/sheets/{sheetId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → 204 No Content

If the id does not exist or is not accessible with your API key, you get 404 Not Found:

Code
 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found."
  }
}

Re-deleting the same id returns 404, so retries are safe.

Deleting in bulk

Send up to 100 ids in one call. Each id is processed independently — the operation is not all-or-nothing.

Code
 
curl -X POST "https://api.calcs.com/v1/projects/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectIds": ["0ad00c8b-03e9-467c-aa29-27d28f6a056f", "662f0b28-3c2e-4dae-a61b-1bdfa367373b"]}'

The sheet route is identical, with a sheetIds array:

Code
 
curl -X POST "https://api.calcs.com/v1/sheets/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sheetIds": ["8b569763-56f7-41bb-a5fe-8c44e7cf5459"]}'

The response lists one result per id, in request order. When every id is deleted you get 200 OK:

Code
 
{
  "results": [
    { "id": "0ad00c8b-03e9-467c-aa29-27d28f6a056f", "status": "deleted" },
    { "id": "662f0b28-3c2e-4dae-a61b-1bdfa367373b", "status": "deleted" }
  ]
}

When at least one id fails, the overall status is 207 Multi-Status and the failed items carry a code. The successful ids are still deleted:

Code
 
{
  "results": [
    { "id": "0ad00c8b-03e9-467c-aa29-27d28f6a056f", "status": "deleted" },
    { "id": "662f0b28-3c2e-4dae-a61b-1bdfa367373b", "status": "error", "code": "NOT_FOUND" }
  ]
}

Inspect each item's status ("deleted" or "error") rather than relying on the HTTP status alone — a 207 tells you some item failed, and the per-item code tells you which and why.

A failed item carries one of these codes:

code	Meaning	What to do
NOT_FOUND	The id does not exist, or is not accessible with this API key.	Nothing — the id is already absent.
UPSTREAM_ERROR	The deletion could not be completed. The id may still exist.	Retry this id; if it persists, contact support.

Treat an unrecognised code as a retryable failure.

Request validation

The bulk request is rejected with 422 Unprocessable Entity (before anything is deleted) when the id array is missing, empty, contains a non-UUID, contains duplicate ids, or has more than 100 ids — the list is never silently truncated. Send each id at most once; ids are compared case-insensitively, so two spellings of the same UUID count as duplicates:

Code
 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "projectIds cannot contain more than 100 ids.",
    "details": [
      { "field": "projectIds", "message": "projectIds cannot contain more than 100 ids." }
    ]
  }
}

Notes

• Deleting a project takes its sheets with it. A deleted project's sheets stop appearing (e.g. in GET /v1/projects/{projectId}/sheets, which returns an empty list) and are inaccessible while the project is deleted. You don't need to delete a project's sheets separately — and requests targeting them return 404.
• Idempotent in outcome. Re-sending the same delete leaves the server in the same state. A repeated single delete returns 404; in a bulk call, an already-deleted id comes back as a per-item NOT_FOUND.