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

# Delete Facilities (v2)

> Delete up to 1,000 facilities and their data, asynchronously, as an ingest job

[← Facilities API](/api-reference/facilities/overview)

Delete facilities by id, **with everything they hold**: invoices, wastes, waste water treatments and their emissions.
The request checks every id, takes the facilities out of every list at once and answers `202 Accepted` with a
**job**; the data is deleted in the background, one facility at a time. Follow it with
[`GET /v2/ingest-jobs/{id}`](/api-reference/ingest-jobs/get) or the [`ingest_job.finished`](/api-reference/webhooks/overview) webhook.

<Warning>
  **Permanent.** Deleted facilities and all their data cannot be recovered. Use `dry_run=true` first if you are not sure.
</Warning>

<Warning>
  **Beta.** Part of the bulk ingest API, currently in beta. The contract may still change before general availability.
</Warning>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v2/facilities/delete" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Idempotency-Key: 2a4c6e80-1b3d-4f5a-9c7e-0d2f4a6b8c1e" \
    -H "Content-Type: application/json" \
    -d '{"ids": ["0b8e4d2a-1c3f-4e5a-9b7d-6c8e0f2a4b6d"]}'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import uuid

  import requests

  response = requests.post(
      "https://api.dcycle.io/v2/facilities/delete",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
          "Idempotency-Key": str(uuid.uuid4()),  # keep it to retry this same batch
      },
      json={"ids": ["0b8e4d2a-1c3f-4e5a-9b7d-6c8e0f2a4b6d"]},
      timeout=60,
  )
  response.raise_for_status()
  job = response.json()
  print(job["id"], job["status"])
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');
  const { randomUUID } = require('crypto');

  const { data: job } = await axios.post(
    'https://api.dcycle.io/v2/facilities/delete',
    { ids: ['0b8e4d2a-1c3f-4e5a-9b7d-6c8e0f2a4b6d'] },
    {
      headers: {
        'x-api-key': process.env.DCYCLE_API_KEY,
        'x-organization-id': process.env.DCYCLE_ORG_ID,
        'Idempotency-Key': randomUUID(), // keep it to retry this same batch
      },
    },
  );
  console.log(job.id, job.status);
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "4e3d2c1b-0a9f-4e8d-9c7b-6a5f4e3d2c1b",
    "status": "processing",
    "entity_type": "facilities",
    "operation": "delete",
    "source": "api_bulk",
    "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
    "chunks_total": 1,
    "chunks_done": 0,
    "created_at": "2026-10-07T09:20:03.512Z",
    "finished_at": null,
    "links": {
      "self": "/v2/ingest-jobs/4e3d2c1b-0a9f-4e8d-9c7b-6a5f4e3d2c1b",
      "items": "/v2/ingest-jobs/4e3d2c1b-0a9f-4e8d-9c7b-6a5f4e3d2c1b/items"
    }
  }
  ```

  ```json 422 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
    "title": "Unprocessable Content",
    "status": 422,
    "code": "BULK_RECORDS_REJECTED",
    "detail": "1 of the submitted records are invalid; nothing was written.",
    "errors": [
      {
        "source_row_index": 0,
        "client_row_id": null,
        "error_code": "NOT_FOUND",
        "error_params": { "field": "ids", "value": "0b8e4d2a-1c3f-4e5a-9b7d-6c8e0f2a4b6d" }
      }
    ],
    "rejected": 1,
    "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
  }
  ```

  ```json 200 (dry_run=true) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "dry_run": true, "submitted": 1, "valid": 1 }
  ```
</ResponseExample>

## How it works

1. **The request checks every id.** One that does not exist, is already deleted, is outside your organization's
   perimeter (your organization and its accepted subsidiaries) or is repeated rejects the **whole** request with
   `422` and nothing is deleted.
2. **The facilities disappear at once.** They are disabled in the request, so they no longer appear in
   [List Facilities](/api-reference/facilities/list) and nothing new can be attached to them.
3. **The job deletes their data in the background**, one facility per chunk: invoices, wastes, waste water
   treatments, their emissions and calculation data, and the facility itself. Their supply contracts become
   inactive.
4. **When every chunk is done** the job is `completed` (or `completed_with_errors`), and `ingest_job.finished` is
   sent to your webhook endpoints with `"entity_type": "facilities"` and `"operation": "delete"`.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  1 to 255 characters, unique per batch. A retry with the same key and body returns the original job instead of
  deleting again; the same key with another body is `422 IDEMPOTENCY_KEY_REUSED`.
</ParamField>

### Query Parameters

<ParamField query="dry_run" type="boolean" default="false">
  Check only: the same `422` for bad ids, nothing deleted or disabled, no job; `200` with `{"dry_run": true,
      "submitted": n, "valid": n}` when every id would be deleted.
</ParamField>

### Body Parameters

<ParamField body="ids" type="array[uuid]" required>
  Facility ids to delete, 1 to 1,000, each once.
</ParamField>

## Response

`202 Accepted`, the job (`operation: delete`) and a `Location` header to it. Per-id outcomes are in
[`GET /v2/ingest-jobs/{id}/items`](/api-reference/ingest-jobs/list-items): one item per id, in the order sent, with
`stage: delete` and `entity_id` = the facility id.

## Errors

[Problem details](/api-reference/errors). Per-id codes in `errors[].error_code`:

| `error_code` | Cause |
| - | - |
| `NOT_FOUND` | The id does not exist, is already deleted or is outside your organization's perimeter (all answer the same). |
| `DUPLICATE_ID` | The id appears more than once in `ids`. |

`401` for a missing or invalid API key, `403 LOGGED_USER_NOT_MEMBER` when the key's user is not a member of the
organization, `422 REQUEST_VALIDATION_FAILED` for a malformed body (empty `ids`, more than 1,000, not UUIDs).

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Facilities (v2)" icon="plus" href="/api-reference/facilities/create-v2">
    Create up to 1,000 facilities in one request
  </Card>

  <Card title="Get Ingest Job" icon="magnifying-glass" href="/api-reference/ingest-jobs/get">
    Follow the deletion
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.