GET /inventory: List bookable ad slots

DataFlair calls this endpoint to learn about your ad slots. An operator then maps DataFlair placements to your inventory_id values without copying ids by hand. For what an inventory_id is, see Inventory identity.

What we send

HTTP

GET /inventory?limit=100&cursor=eyJsYXN0X2lkIjoic2xvdF80MTAifQ HTTP/1.1
Host: ads.example.com
Authorization: Bearer sk_live_9f2c…

curl

curl "$BASE_URL/inventory?limit=100" \
  -H "Authorization: Bearer $API_KEY"

Query parameter	Required	Meaning
limit	no	Page size. Default 50, minimum 1, maximum 200.
cursor	no	The opaque cursor from the previous response's next_cursor.

When DataFlair connects your platform, it calls GET /inventory?limit=1. It needs only a successful answer with a data array to confirm the inventory_read capability.

What you return

Status 200 with a JSON body:

exemplary/inventory/expected-response.json

{
  "data": [
    {
      "inventory_id": "slot_728x90_home",
      "name": "Homepage Leaderboard",
      "sizes": [
        "728x90",
        "970x250"
      ],
      "format": "display",
      "status": "active"
    },
    {
      "inventory_id": "slot_300x250_article",
      "name": "Article MPU",
      "sizes": [
        "300x250"
      ],
      "format": "display",
      "status": "active"
    }
  ],
  "next_cursor": "eyJsYXN0X2lkIjoic2xvdF8zMDAifQ"
}

The JSON on this page is read from the fixture files, so it cannot drift from the test suite.

Fields

Field	Type	Required	Meaning
data	array	yes	The slots on this page.
data[].inventory_id	string	yes	The stable, opaque id described on Inventory identity.
data[].name	string	yes	A human label shown to the operator while mapping.
data[].sizes	array of strings	yes	Accepted creative sizes, each as WIDTHxHEIGHT, for example 728x90. DataFlair uses them for size compatibility checks.
data[].format	string	no	display, video, native and so on. Free-form, so keep it consistent across slots.
data[].status	string	no	active or archived, so DataFlair can hide dead slots.
next_cursor	string or null	no	The cursor for the next page. Leave it out, or return null, on the last page.

Paging follows the cursor rules in Conventions. Read next_cursor until it is absent.

Errors

Status	What caused it	What DataFlair does	What to do
400	Malformed request.	Treats it as a bug, logs it and shows it.	Check the query parameters.
401	Missing, invalid or expired key.	Marks the connection as error. The operator re-checks the credential.	Check the key.
403	The key lacks a required scope.	Marks the connection as error. The operator widens the scope.	Give the key read scope.
429	Rate limit exceeded.	Backs off and retries per Retry-After.	Send a Retry-After header in seconds.
5xx	Server error.	Retries with backoff. A persistent 5xx shows as "your platform is unreachable".	Check your server's logs.

Today, DataFlair calls this endpoint in one place: the connect step, with limit=1. A failure there does not fail the connection. It leaves Inventory read as Not verified. The reactions in the table come from the contract in Conventions.

Every error body has the shape described in Conventions.

Timeouts and retries

DataFlair waits up to 10 seconds to connect and 30 seconds in total for this call. These are the platform's configured defaults. DataFlair does not retry a failed GET /inventory probe.

Verify

Run the conformance check with --only inventory to check this endpoint against the fixtures.

Verify this endpoint

node tools/adserver-check/bin/adserver-check.mjs http://localhost:3000/api/v1 --key sk_test_local --only inventory

No playground here: the request would go to your own server. Run the checker.

The checker is not published to npm yet. See how to run it.