Quickstart

From no account to a live response in five steps.

Create a free account at portal.thesma.dev/signup. No credit card, no dataset selection — every tier includes all four data verticals (SEC EDGAR, US Census, US BLS, US SBA).

2. Generate an API key

On first login the portal auto-generates a key. You can also create additional keys at portal.thesma.dev/dashboard → API keys.

Keys look like:

gd_live_a1b2c3d4e5f6...

The plaintext key is shown once at creation. Save it somewhere safe — the server only stores a SHA-256 hash, so there is no way to recover a lost key. Revoke and reissue if you lose one.

3. Make your first call — curl

Fetch the most recent annual financials for Apple (AAPL):

curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL/financials?statement=income&period=annual&per_page=1"

You should see a JSON response with a data array containing one income-statement element:

{
  "data": [
    {
      "company": {
        "cik": "0000320193",
        "ticker": "AAPL",
        "name": "Apple Inc."
      },
      "statement": "income",
      "period": "annual",
      "fiscal_year": 2025,
      "fiscal_quarter": null,
      "fiscal_year_end": "2025-09-27",
      "filing_accession": "0000320193-25-000079",
      "taxonomy": "us-gaap",
      "currency": "USD",
      "line_items": {
        "revenue": 416161000000.0,
        "cost_of_revenue": 220960000000.0,
        "gross_profit": 195201000000.0,
        "operating_income": 133050000000.0,
        "pre_tax_income": 132729000000.0,
        "net_income": 112010000000.0,
        "eps_basic": 7.49,
        "eps_diluted": 7.46
      },
      "metadata": {
        "source": "ixbrl",
        "data_completeness": 14,
        "expected_fields": 23
      }
    }
  ]
}

Note: data is always a list, even when per_page=1. Iterate or index data[0] to access fields. Exact field values change as new filings land; the shape is stable.

This endpoint works the same way for US-GAAP and IFRS filers — the response shape is identical, with taxonomy and currency metadata telling you which reporting framework you’re getting. See the IFRS filer recipe for a worked IFRS example.

4. Same call with the Python SDK

pip install thesma

import os
from thesma import ThesmaClient

client = ThesmaClient(api_key=os.environ["THESMA_API_KEY"])

financials = client.sec.companies("AAPL").financials(period="annual", limit=1)
print(financials.data[0].revenue)

The SDK reads THESMA_API_KEY automatically if you omit the api_key= argument.

5. What’s next

Authentication — both header formats, key-format details, real 401/403 shapes.
Rate limits — what you get on each tier, the 429 shape, and Retry-After semantics.
Datasets — coverage, known limitations, endpoint tables for each data vertical.
Recipes — worked examples, starting with the flagship cross-dataset labor-context enrichment.
API Reference — full endpoint list, try any request in the browser.

Quickstart

1. Sign up

2. Generate an API key

3. Make your first call — curl

4. Same call with the Python SDK

5. What’s next