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

# Quick Start

> Authenticate and make your first Corpus API request in a few minutes.

Make a request against the unversioned production API, inspect its named response envelope, and then switch between the US, India, and China namespaces.

## 1. Create an API key

Corpus is self-serve. Sign up at [corpus.apart.io/signup](https://corpus.apart.io/signup) with an email and password, then create a key from your account page — there is no approval step, and your account is provisioned with 100,000 credits. Keep the key in an environment variable:

```bash theme={"dark"}
export CORPUS_API_KEY="ck_live_your_key_here"
```

The key is shown once at creation and cannot be retrieved afterwards; create a new one and revoke the old if you lose it.

Every authenticated request sends the key in the `X-API-KEY` header. `GET /catalog` is public and free; every other request costs credits and requires a key. Self-serve keys carry the full public surface — `us:read`, `india:read`, `china:read`, `search:read`, `rag:search`, `litigation:read`, and `data:export`.

See [Authentication](https://docs-corpus.apart.io/authentication.md) for credit costs and key management.

> [!WARNING]
>
> Never place a long-lived Corpus API key in browser JavaScript. A frontend should call its own server route, which adds the key before forwarding the request to Corpus.

## 2. Make your first request

Request the latest available US income statement for Apple:

> [!TIP]
>
> Python requires `requests` (`python -m pip install requests`). The JavaScript example uses Node.js 18 or later, where `fetch` is built in.

```python Python theme={"dark"}
import os
import requests

url = "https://api-corpus.apart.io/us/financials/income-statements"
headers = {"X-API-KEY": os.environ["CORPUS_API_KEY"]}
params = {
    "ticker": "AAPL",
    "limit": 1,
}

response = requests.get(url, params=params, headers=headers, timeout=30)
response.raise_for_status()

for statement in response.json()["income_statements"]:
    revenue = statement["revenue"]
    value = f"${revenue:,.0f}" if revenue is not None else "not reported"
    print(f"{statement['report_period']}: Revenue = {value}")
```

```javascript JavaScript theme={"dark"}
const url = new URL(
  "https://api-corpus.apart.io/us/financials/income-statements",
);
url.search = new URLSearchParams({
  ticker: "AAPL",
  limit: "1",
});

const response = await fetch(url, {
  headers: { "X-API-KEY": process.env.CORPUS_API_KEY },
});

if (!response.ok) {
  throw new Error(`Corpus request failed: ${response.status}`);
}

const { income_statements: statements } = await response.json();
for (const statement of statements) {
  const revenue =
    statement.revenue === null
      ? "not reported"
      : `$${statement.revenue.toLocaleString()}`;
  console.log(`${statement.report_period}: Revenue = ${revenue}`);
}
```

```bash cURL theme={"dark"}
curl "https://api-corpus.apart.io/us/financials/income-statements?ticker=AAPL&limit=1" \
  --header "X-API-KEY: $CORPUS_API_KEY"
```

The endpoint returns the most recent available income-statement periods in descending report-date order. Results can include annual and quarterly periods; inspect each record's `period` and `fiscal_period`. The response uses the `income_statements` resource name and includes metadata about jurisdiction, record count, normalization version, and provenance:

```json theme={"dark"}
{
  "income_statements": [
    {
      "ticker": "AAPL",
      "report_period": "2025-09-27",
      "fiscal_period": "FY",
      "period": "annual",
      "currency": "USD",
      "accession_number": "0000320193-25-000079",
      "filing_date": "2025-10-31",
      "filing_datetime": "2025-10-31T06:01:26-04:00",
      "revenue": 416161000000,
      "gross_profit": 195201000000,
      "operating_income": 133050000000,
      "net_income": 112010000000
    }
  ],
  "meta": {
    "jurisdiction": "US",
    "count": 1,
    "normalization_version": "corpus-financials/v1",
    "as_of": "2026-07-23T08:34:25Z",
    "provenance": {
      "provider": "Corpus",
      "point_in_time": true,
      "knowledge_time_cutoff": "2026-07-23T08:34:25+00:00"
    }
  }
}
```

The statement above is an abbreviated example, and `meta.as_of` is the request time when the parameter is omitted. Add an explicit `as_of` cutoff when you need a reproducible historical read. The current provenance object names Corpus as the serving provider, indicates whether the read is point-in-time, and records the knowledge-time cutoff applied to the query. Nullable response fields are defined in the API reference.

## 3. Choose the correct country namespace

US endpoints accept US identifiers. India endpoints accept Indian identifiers; they do not translate an ISIN into a US ticker model.

Request an Indian security by ISIN:

```bash theme={"dark"}
curl "https://api-corpus.apart.io/india/securities?isin=INE002A01018&limit=1" \
  --header "X-API-KEY: $CORPUS_API_KEY"
```

The response uses the India security schema:

```json theme={"dark"}
{
  "securities": [
    {
      "isin": "INE002A01018",
      "company_name": "Reliance Industries Limited",
      "nse_symbol": "RELIANCE",
      "bse_code": "500325",
      "is_active": true
    }
  ],
  "meta": {
    "jurisdiction": "IN",
    "count": 1
  }
}
```

## 4. Explore more endpoints

### Find a recent 10-K

```bash theme={"dark"}
curl "https://api-corpus.apart.io/us/filings?ticker=AAPL&filing_type=10-K&limit=1" \
  --header "X-API-KEY: $CORPUS_API_KEY"
```

### Retrieve one filing section

```bash theme={"dark"}
curl "https://api-corpus.apart.io/us/filings/items?ticker=AAPL&filing_type=10-K&year=2025&item=Item-1A" \
  --header "X-API-KEY: $CORPUS_API_KEY"
```

### Read an Indian annual-report catalog

```bash theme={"dark"}
curl "https://api-corpus.apart.io/india/filings?company=RELIANCE&year=2022&limit=5" \
  --header "X-API-KEY: $CORPUS_API_KEY"
```

### Search US filing text

```bash theme={"dark"}
curl --request POST "https://api-corpus.apart.io/us/search" \
  --header "X-API-KEY: $CORPUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"query":"supply chain risk","limit":5}'
```

Search requires both `us:read` and `search:read`. India search similarly requires `india:read` and `search:read`; court records additionally require `litigation:read`.

## 5. Handle pagination and processing state

Offset-paginated collection endpoints include `limit`, `offset`, and `next_offset` in `meta`. Continue while `next_offset` is not `null`. Some resources, including prices and financial statements, are limit-only; follow the parameters in that endpoint's API reference.

Some EDGAR documents are still moving through archival or parsing. Filing content endpoints return `503` with `Retry-After` when processing is incomplete. Do not treat a metadata row as proof that normalized text or filing items are already available.

## What next?

> [card] [United States API](https://docs-corpus.apart.io/us/overview.md)
>
> Companies, prices, financial statements, SEC filings, ownership, events, and search.

> [card] [India API](https://docs-corpus.apart.io/india/overview.md)
>
> Securities, prices, annual reports, news, judgments, exports, and search.

> [card] [MCP server](https://docs-corpus.apart.io/mcp-server.md)
>
> Connect compatible agents to read-only US, India, and internal China tools.

> [card] [Authentication](https://docs-corpus.apart.io/authentication.md)
>
> Understand scopes and safe frontend integration.

> [card] [Errors and pagination](https://docs-corpus.apart.io/errors-and-pagination.md)
>
> Handle validation, authorization, rate limits, and processing state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.