Delivery API

The delivery API lets your pipeline pull new batches without anyone opening the buyer portal. It returns the same licences and batches you see in the portal under Deliveries.

#Authentication

Create a key in the buyer portal under API keys. Send it as a bearer token:

curl https://datayield.ai/api/v1/buyer/licences \
  -H "Authorization: Bearer $DATAYIELD_BUYER_KEY"

Buyer keys start with dyb_live_ or dyb_test_. We store only a hash, so copy the key when you create it. Revoke a key in the portal and it stops working at once.

Seller keys (dy_live_...) don't work here, and buyer keys don't work on the seller API. Both return 401.

Test keys see the same licences and batches as live keys. Downloads made with a test key are marked as test in your download history.

Errors use the same shape as the rest of the API: { "error": { "code": "...", "message": "..." } }. See Errors.

#GET /api/v1/buyer/licences

Lists your licences, newest first, with the prices you pay.

{
  "licences": [
    {
      "id": "6f1c...",
      "status": "active",
      "dataset": {
        "id": "a2b9...",
        "title": "UK bookkeeping ledgers",
        "industry": "accounting",
        "product": "records",
        "seller": "a mid-size UK bookkeeping firm"
      },
      "uses": ["training"],
      "term_months": 12,
      "exclusive": false,
      "starts_on": "2026-09-01",
      "ends_on": "2027-08-31",
      "history_price_cents": 4000000,
      "refresh_price_cents": 250000,
      "refresh_active": true
    }
  ]
}

refresh_price_cents is null when the licence has no monthly refresh.

#GET /api/v1/buyer/licences/:id/batches

Lists the batches you can download under one licence, newest first. Only accepted batches appear. A licence without a refresh term includes batches up to the month it started. Batches are hidden while an invoice on the licence is overdue and come back once it is paid.

{
  "licence": { "id": "6f1c...", "status": "active" },
  "batches": [
    {
      "id": "c03e...",
      "licence_id": "6f1c...",
      "period": "2026-10",
      "product": "records",
      "record_count": 1840,
      "accepted_at": "2026-10-04T09:12:00Z",
      "sha256": "9b1f...",
      "schema": { "format": "jsonl", "objects": { "invoice": [] } }
    }
  ]
}

period is the month the batch covers. schema lists the columns, as described in Data formats. Returns 404 if the licence isn't yours.

#GET /api/v1/buyer/batches/:id/download

Returns a signed URL for one batch. The URL works for 5 minutes, so request it just before you download. Each call is logged as a delivery and shows in your download history.

{
  "url": "https://...",
  "expires_at": "2026-10-12T14:05:00Z",
  "batch": { "id": "c03e...", "period": "2026-10", "record_count": 1840, "sha256": "9b1f..." }
}

The file is gzipped JSON Lines. Check it against sha256 after you download it:

URL=$(curl -s https://datayield.ai/api/v1/buyer/batches/$BATCH/download \
  -H "Authorization: Bearer $DATAYIELD_BUYER_KEY" | jq -r .url)
curl -s "$URL" -o batch.jsonl.gz
shasum -a 256 batch.jsonl.gz

Returns 404 if the batch isn't one you can download, for example because your licence has ended.

#Polling for new batches

New batches arrive once a month for licences with a refresh term. Call the batches endpoint once a day and download any id you haven't seen. There is no charge per download.