API documentation

1. Authentication

A key is created from your account. It is shown once: we only keep its fingerprint, so a lost key cannot be recovered, only replaced.

curl -s "https://edge-lab.io/api/v1/matches" \
  -H "Authorization: Bearer $EDGELAB_API_KEY"

Without a valid key: 401. A revoked key stops working on the very next call, with no delay and no cache: that is what makes revocation credible, and it is also why the key is checked against the database on every request.

2. The response envelope

A success always carries { "data": …, "meta": … }, an error always { "error": { "code": …, "message": … } }. Error codes are stable: unauthorized, bad_request, not_found, rate_limited, incomplete_response.

Test error.code, never the message: the message is written for a human and may be reworded; the code is part of the contract.

3. Quotas and limit headers

Two plans, and they are not counted the same way.

• Trial: 20 calls in total, for life. There is no window that reopens, hence no Retry-After: the message tells you to subscribe, not to wait. Replacing your key does not give back the calls you used.
• Subscription: 2000 calls per Paris day. The window reopens at midnight Paris time, and X-RateLimit-Reset says when.

Every response, successes included, carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window (day or lifetime). Going over returns 429, never a truncated response.

4. The viewer parameter, and what your plan does with it

Three routes accept ?viewer=free|premium. The key says who is calling; viewer says for whom you are asking: you are the authority on the tier of YOUR readers. When absent, it defaults to premium.

⚠️ The plan of the key caps this parameter. A trial key is served with viewer=free whatever it asks for: model probabilities and their weights, the value signal, the score matrix and serve statistics are absent from the body, which then carries locked: true. That is what the trial shows: the shape of the responses, not the data we sell. GET /api/v1/capabilities answers from the point of view of YOUR key and says so explicitly.

An unknown value returns 400: we do not guess on your behalf.

5. Endpoints

This list is produced by the API's own catalogue. It cannot announce a route that does not exist, nor forget one that does.

GET /api/v1/capabilities serves the same thing as JSON, with the fields of each response and their tier: a client can adapt without re-reading this page.

6. Two reading rules that avoid surprises

Player identifiers are opaque. A player_key only means something inside this API: compare them to each other, do not interpret them, do not join them to any external source. The same player has one identifier per tour, and a key may be null on an older match whose identity is not certain: treat that as « unknown identity », never as « invalid match ».

Nothing is recomputed after the fact. A value signal is frozen at the moment of the prediction, and the analysis of a started match shows the pre-match picture. That is what makes the track record verifiable, and it is also why a value will never change retroactively in your responses.

7. Versioning

The /api/v1 prefix is stable. We may add fields or routes without notice: your client must ignore what it does not know. Removing or renaming an existing field would require a new version.

8. What the contract allows

Use of the API is governed by the API Terms, a contract separate from the site's. In two words: embedding our analyses inside your product, yes; reselling the feed as it comes or rebuilding the database, no.

A question, a volume need, a particular use case: hello@edge-lab.io.