Skip to main content
POST
← Wastes API Delete wastes by id. The request checks every id and answers 202 Accepted with a job (see how bulk ingestion works); the deletion runs in the background, chunk by chunk, so thousands of ids never hold your request open. Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook.
Permanent. Deleted wastes and their emissions cannot be recovered. Use dry_run=true first if you are not sure.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

How it works

  1. The request checks every id. One that does not exist, is outside your perimeter or is repeated rejects the whole request with 422 and nothing is deleted.
  2. The job deletes in the background, 500 ids per chunk, together with each waste’s emissions and calculation data. A waste that someone else deleted in the meantime ends failed with DELETE_FAILED; the others go on. So does a waste that could not be deleted: List Ingest Job Items says what to do.
  3. When every chunk is done the job is completed (or completed_with_errors), and, for a job submitted with an API key, ingest_job.finished is sent to your webhook endpoints with "operation": "delete".

Request

Headers

string
required
Your API key (see Authentication).Example: ${DCYCLE_API_KEY}
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
required
1 to 255 characters, one per batch. It is looked up per organization across every v2 bulk route, creates included: do not reuse the key of the batch that created the wastes. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true) instead of deleting again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free and a request with it is a new one. See The Idempotency-Key.

Query Parameters

boolean
default:"false"
Check only: the same 422 for bad ids, nothing deleted, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every id would be deleted. The Idempotency-Key header is still required, but a dry run does not check or store it.

Body Parameters

array[uuid]
required
Waste ids to delete, 1 to 5,000, each once.A waste created with facility_percentages is one waste per facility, each with its own id, and the create job’s item only gives the first one (see Split one waste across two facilities). Deleting that id removes only that share. If you may need to delete such a waste later, create it as one record per facility instead, so every share has its own item and id.To delete every share of a split you already created, start from the item’s entity_id:
  1. GET /v1/wastes/{entity_id}/detail returns the facilities of the split in facility_percentages[].facility_id.
  2. For each of those facilities, GET /v1/wastes?facility_id=… (every page) and keep the rows whose source_invoice_id equals that entity_id.
  3. Send all their ids in one request.

Response

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

Errors

Problem details. Per-id codes in errors[].error_code: The API key and the organization are checked as in Create Wastes: 401, 400 ORGANIZATION_ID_REQUIRED and 403 (LOGGED_USER_NOT_MEMBER, API_KEY_SCOPE_DENIED, VIEWER_CANNOT_WRITE), each in Errors. Then 422 REQUEST_VALIDATION_FAILED for a malformed body (empty ids, more than 5,000, not UUIDs), 422 IDEMPOTENCY_KEY_REUSED and 409 IDEMPOTENCY_KEY_IN_PROGRESS.

Create Wastes (v2)

Create up to 5,000 wastes in one request

Get Ingest Job

Follow the deletion