Skip to main content
POST
Create wastes: one, or up to 5,000 in a single request. The records are validated and stored at once, and their CO2e emissions are calculated asynchronously by a background worker. The response is an ingest job, not the wastes themselves: you poll the job to follow the calculation and read per-record outcomes.
Beta. This endpoint is in beta: the contract may still change before general availability. Pin your integration to the fields documented here and handle unknown fields in responses gracefully. Feedback is welcome through your Dcycle contact.

How it works

  1. You send a list of records (records), one object per waste.
  2. All or nothing: every record is validated. If any record is invalid, the whole request is rejected with 422 BULK_RECORDS_REJECTED, the response lists every invalid record, and nothing is written. Fix them and resend the full batch.
  3. If every record is valid, all wastes are written in one transaction and the API answers 202 Accepted with the ingest job and a Location header pointing at it.
  4. A worker calculates the emissions in chunks of 100 records. Poll GET /v2/ingest-jobs/{job_id} until status is completed or completed_with_errors, then read the per-record outcomes at GET /v2/ingest-jobs/{job_id}/items.

One waste or many

The same request creates one waste or a whole batch. To create a single waste, send records with one element; it goes through the same validation, the same job and the same calculation as a batch. For more than 5,000 records, split them into several requests (see Limits).

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
UUID of the organization the wastes are created for. Facilities of its accepted, enabled subsidiaries are also valid destinations.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
required
Must be application/json
string
Strongly recommended. Up to 255 characters. Send a unique value per batch (a UUID works well). If a request with the same key was already accepted for this organization, the API returns that same job instead of creating the wastes again, so a timeout or network error can be retried safely. Use a new key for a new batch. Without it, a retried request creates the wastes twice.Example: c41d8e77-5d40-4a11-9e8b-2c9f4d1e7a03

Body Parameters

array[object]
required
The wastes to create: between 1 and 5,000 objects. Each record has the fields below.
custom_ef_record_id (custom emission factors) is not supported yet: a record that sends it is rejected with CUSTOM_EF_RECORD_NOT_SUPPORTED. custom_emission_factor_id is accepted but ignored.

Response

202 Accepted

Every record passed validation and was stored. The body is the ingest job; the Location header holds its path.
uuid
Ingest job id. Use it with GET /v2/ingest-jobs/{job_id}.
string
processing right after the request. See Job status.
string
Always wastes for this endpoint.
string
Always create.
string
Always api_bulk for this endpoint.
object
integer
Number of calculation chunks (100 records each).
integer
Chunks already calculated. chunks_done / chunks_total is the job’s progress.
datetime
When the job was created (UTC).
datetime | null
When the last chunk finished (UTC), null while the job is processing.
self: the job. items: its per-record outcomes.

Job status

While a job is processing, the new wastes already exist with co2e at 0; the value is filled in when their chunk is calculated. Each record’s waste id is its entity_id in the job’s items.

Errors

All error bodies have a stable code and a detail.

422 BULK_RECORDS_REJECTED — invalid records

At least one record is invalid. Nothing was written. detail.rejected is the number of invalid records and detail.records lists them (up to 100) in submission order, each with its position in records (source_row_index, starting at 0), your client_row_id and a stable error_code.

422 — malformed body

The body itself is invalid: records is missing or empty, or has more than 5,000 entries. The body follows the standard validation format:

401 Unauthorized / 403 Forbidden

Missing or invalid API key (401), or the API key’s user is not a member of the organization in x-organization-id (403 LOGGED_USER_NOT_MEMBER).

Examples

Create a batch and wait for the calculation

Split one waste across two facilities

This creates two wastes (60 and 40 units) sharing one source_waste_id. The job has one item for the record, whose entity_id is the first waste of the group.

Retries and idempotency

  • Network error or timeout: retry with the same Idempotency-Key. If the first request was accepted, you get the same job back and no wastes are duplicated.
  • 422 BULK_RECORDS_REJECTED: nothing was stored. Fix the records and send the batch again (a new key is fine, since the first request created nothing).
  • Without an Idempotency-Key, sending the same batch twice creates the wastes twice.

Limits

Get Ingest Job

Status and progress of the batch

List Ingest Job Items

Per-record outcomes, including calculation failures