> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> How to read the Alterscope API reference — base URL, auth, the response envelope, and pagination conventions.

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:

```bash theme={null}
curl -s https://api.alterscope.org/v2/... \
  -H "Authorization: Bearer sk_live_..."
```

Keys are issued and scoped per organization. See [Authentication](/develop/get-started/authentication) for issuing keys and [Scopes & permissions](/develop/get-started/scopes) 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](/develop/concepts/response-envelope) and [Agentic envelope](/develop/concepts/agentic-envelope); the trust framing is on [Freshness & quality](/trust/data/freshness-and-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](/api-reference/pagination) 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](/develop/get-started/errors). Per-tier request rates and quotas are on [Rate limits & tiers](/develop/get-started/rate-limits).

## 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](/api-reference/versioning) and the [data coverage manifest](/api-reference/data-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
```

<Note>
  First-party SDKs cover TypeScript ([`@alterscope/sdk`](/develop/sdks/typescript)) and Python ([`alterscope`](/develop/sdks/python), Beta). For any other language, generate a client from this spec with [openapi-generator](https://openapi-generator.tech/) — the wire contract is identical regardless of how you call it.
</Note>

### Generate a client

```bash theme={null}
# 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](https://openapi-generator.tech/docs/generators) (`go`, `java`, `csharp`, `rust`, …). Authenticate generated requests the same way as everywhere else — `Authorization: Bearer sk_live_...` against `https://api.alterscope.org`. See [Authentication](/develop/get-started/authentication) for issuing keys.