GET /health: Connect and verify

DataFlair calls this endpoint first, when an operator connects your platform. It is a cheap, read-only request. It confirms three things at once: your credential works, DataFlair reached the right account, and DataFlair can read your account context.

What we send

HTTP

GET /health HTTP/1.1
Host: ads.example.com
Authorization: Bearer sk_live_9f2c…

curl

curl "$BASE_URL/health" \
  -H "Authorization: Bearer $API_KEY"

DataFlair appends /health to the base URL you entered. A base URL of https://ads.example.com/api/v1 gives https://ads.example.com/api/v1/health. If your base URL has a query string, DataFlair keeps it and puts the path before it.

What you return

Status 200 with a JSON body:

exemplary/health/expected-response.json

{
  "account_id": "acct_1029",
  "account_name": "Example Media Network",
  "timezone": "Europe/Berlin",
  "currency": "EUR",
  "capabilities": {
    "forecast": true,
    "reporting": true,
    "draft_booking": true
  }
}

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

Fields

Field	Type	Required	Meaning
account_id	string	yes	Your id for the account. It must not be empty.
account_name	string	no	Display only. DataFlair shows it on the connection card.
timezone	string	yes	The IANA timezone your platform books flights in, for example Europe/Berlin. DataFlair sends and reads all flight dates in this zone. A value that is not a real IANA identifier, such as UTC+2, is rejected.
currency	string	yes	ISO-4217 code in three uppercase letters, for example EUR. DataFlair checks that a booking's currency matches it before it pushes an order. A value such as EURO is rejected.
capabilities	object	yes	Three flags, each a JSON boolean.
capabilities.forecast	boolean	yes	Whether POST /forecast works. Declare true. false is a degraded state: DataFlair then shows the availability you list instead of a live forecast.
capabilities.reporting	boolean	yes	Declare true. A response with false is rejected.
capabilities.draft_booking	boolean	yes	Declare true. A response with false is rejected.

inventory_read is not in this object. You cannot turn GET /inventory off, so there is nothing to declare. DataFlair confirms it the first time a real GET /inventory call succeeds.

Errors

Status	What caused it	What the operator sees in DataFlair	What to do
401	Missing, invalid or expired key.	State auth_error: "DataFlair could not authenticate. Check your API key, then reconnect."	Check the key. Issue a new one if needed.
403	The key authenticated but lacks a required scope.	State forbidden: "Your API key doesn't have the required scope. Update its permissions on your ad server, then reconnect."	Give the key read, create-draft and report scope.
400, 404, 429, any other 4xx, any 5xx, or no answer	Malformed request, wrong base URL, rate limit, server error, or a timeout.	State unreachable: "Your ad server could not be reached. Check the base URL, then reconnect."	Check the base URL, then check your server's logs.
200 with a body that does not match the fields above	A missing or empty account_id, an invalid timezone or currency, a capabilities flag that is not a boolean, or reporting or draft_booking set to false.	State invalid_response: "Your ad server responded, but not in the documented /health shape. Check your /health endpoint, then reconnect."	Fix the body. See Fields.

DataFlair also stores the message from your error body as the last error, with credentials redacted. Return a JSON body of the form { "code": "...", "message": "..." }, as described in Conventions. Do not put secrets in message.

DataFlair does not follow redirects. Serve /health at the exact base URL you entered.

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 /health call. The operator presses Re-verify in DataFlair to try again.

DataFlair resolves your host on every call. The host must resolve to public addresses only. A host that resolves to a private, loopback or internal address is refused.

Verify

Run the conformance check with --only health 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 health

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.