Skip to main content
The Endpoints group in this section is generated directly from the API’s OpenAPI specification, so it always matches what the API actually serves. This page covers the conventions that apply across every endpoint.

​
Base URL

https://api.alterscope.org
All endpoints are versioned under /v2 (a small number of operational endpoints live under /v1). Full request/response schemas for every path are listed in the Endpoints group in the sidebar, generated from the live spec.

​
Authentication

Requests authenticate with an API key sent as a bearer token: 
curl -s https://api.alterscope.org/v2/... \
  -H "Authorization: Bearer sk_live_..."
Keys are issued and scoped per organization. See Authentication for issuing keys and Scopes & permissions for what a key can access.

​
The response envelope

Every response wraps its payload in a consistent envelope: the data, plus a meta._agentic block carrying freshness, a quality verdict, confidence, and provenance. This is what lets you tell, per call, how much to trust a number. The full field reference is on Response envelope and Agentic envelope; the trust framing is on Freshness & quality.

​
Pagination & filtering

List endpoints page with an opaque cursor and a limit, and return paging state in meta:
  • Pass limit to set the page size (each endpoint documents its max).
  • Pass the previous response’s meta.cursor as cursor to fetch the next page; meta.has_more tells you when to stop.
  • Endpoint-specific filters (e.g. scope, min_completeness_pct) are documented per endpoint.
See Pagination, filtering & sorting for the full cursor conventions, a loop-until-done example, and the filter and sort parameters each list endpoint accepts.

​
Errors & rate limits

Errors follow a standard envelope with a machine-readable code and a request_id you should quote in support tickets — see Errors. Per-tier request rates and quotas are on Rate limits & tiers.

​
Reading the reference

The Endpoints group in the sidebar lists every public operation with its parameters, request/response schemas, and examples, generated from the live spec. Cross-cutting policies — versioning & deprecation and the data coverage manifest — are documented as their own pages.

​
Download the OpenAPI spec

The same OpenAPI 3.0 document that generates the Endpoints group is served as a static file: 
https://docs.alterscope.org/openapi-public.yaml
First-party SDKs cover TypeScript (@alterscope/sdk) and Python (alterscope, Beta). For any other language, generate a client from this spec with openapi-generator — the wire contract is identical regardless of how you call it.

​
Generate a client

# Generate a client in the language of your choice (e.g. Go)
openapi-generator-cli generate \
  -i https://docs.alterscope.org/openapi-public.yaml \
  -g go \
  -o ./alterscope-client
Set -g to any supported generator (go, java, csharp, rust, …). Authenticate generated requests the same way as everywhere else — Authorization: Bearer sk_live_... against https://api.alterscope.org. See Authentication for issuing keys.