linkspect API (0.2.0)

Conventions

• Versioning. Resources live under /v1. Within v1, changes are only compatible: new optional fields, new values of extensible enumerations, new resources. Incompatible changes get a new path version.
• API keys. Send Authorization: Bearer <key>. lsk_live_… keys run real measurements; lsk_test_… keys use the fixture engine (see the BearerAuth security scheme).
• Errors. Only when the request itself fails, as RFC 9457 problem details (application/problem+json) with a stable type. A blocked or unreachable site is a successful response with an outcome.
• Idempotency. POST /v1/checks accepts Idempotency-Key: a retry with the same key and body returns the original response.
• Pagination. Lists return items and, if there is a next page, next_cursor; pass it as cursor. limit is 100 by default, at most 200.
• Rate limits. Successful responses carry RateLimit-Policy and RateLimit. Over the limit the API answers 429 with Retry-After.
• IDs are strings with a type prefix and a ULID: chk_ for checks, coh_ for cohort results, msm_ for measurements. Times are RFC 3339 in UTC.
• Enumerations are extensible: new values may appear within v1, so handle unknown values. The nine outcomes are the exception: a closed set.
• Versions in results. Every cohort result names the versions of the engine, decision rules, calibration and geo pack it was produced with.
• Never returned: names of proxy providers, their raw codes and headers, exit IP addresses, or names of payment rails. An exit is described by a pseudonym, ASN, country and connection type.