> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onera.app/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.onera.app/signup](https://corpus.onera.app/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](/authentication) 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.
</Warning>

## 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.
</Tip>

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

  url = "https://corpus-api.onera.app/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://corpus-api.onera.app/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://corpus-api.onera.app/us/financials/income-statements?ticker=AAPL&limit=1" \
    --header "X-API-KEY: $CORPUS_API_KEY"
  ```
</CodeGroup>

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://corpus-api.onera.app/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://corpus-api.onera.app/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://corpus-api.onera.app/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://corpus-api.onera.app/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://corpus-api.onera.app/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?

<CardGroup cols={2}>
  <Card title="United States API" icon="flag-usa" href="/us/overview">
    Companies, prices, financial statements, SEC filings, ownership, events, and search.
  </Card>

  <Card title="India API" icon="building-columns" href="/india/overview">
    Securities, prices, annual reports, news, judgments, exports, and search.
  </Card>

  <Card title="MCP server" icon="robot" href="/mcp">
    Connect compatible agents to read-only US, India, and internal China tools.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Understand scopes and safe frontend integration.
  </Card>

  <Card title="Errors and pagination" icon="circle-exclamation" href="/errors-and-pagination">
    Handle validation, authorization, rate limits, and processing state.
  </Card>
</CardGroup>