Quick Start

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 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:

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 for credit costs and key management.

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:

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

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}")

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}`);
}

curl "https://corpus-api.onera.app/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:

{
  "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:

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:

{
  "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

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

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

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

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?

United States API

Companies, prices, financial statements, SEC filings, ownership, events, and search.

India API

Securities, prices, annual reports, news, judgments, exports, and search.

MCP server

Connect compatible agents to read-only US, India, and internal China tools.

Authentication

Understand scopes and safe frontend integration.

Errors and pagination

Handle validation, authorization, rate limits, and processing state.

Get started

Shared API

Account and credits

Guides

1. Create an API key

2. Make your first request

3. Choose the correct country namespace

4. Explore more endpoints

Find a recent 10-K

Retrieve one filing section

Read an Indian annual-report catalog

Search US filing text

What next?

United States API

India API

MCP server

Authentication

Errors and pagination

​1. Create an API key

​2. Make your first request

​3. Choose the correct country namespace

​4. Explore more endpoints

​Find a recent 10-K

​Retrieve one filing section

​Read an Indian annual-report catalog

​Search US filing text

​5. Handle pagination and processing state

​What next?

United States API

India API

MCP server

Authentication

Errors and pagination

1. Create an API key

2. Make your first request

3. Choose the correct country namespace

4. Explore more endpoints

Find a recent 10-K

Retrieve one filing section

Read an Indian annual-report catalog

Search US filing text

5. Handle pagination and processing state

What next?