Zapi / Docsapi.zedxe.com

Reference docs for integrating the live Zapi API into the main ZedXe product.

Use this page for the product-facing explanation of auth, endpoints, output formats, quota headers, and region caveats. The live Swagger UI remains available on api.zedxe.com/docs for raw endpoint inspection.

Open Live Swagger Back to API Overview

What ships now

Separate product surface

api.zedxe.com stays backend-only. zedxe.com/api becomes the marketing, docs, and signup layer.

Plan-aware auth

Site users graduate from anonymous access to signed JWT access without changing the statement contract.

Canonical financial data

The main site can keep replacing older finance dependencies and standardize on Zapi as the source of record.

Base URL

https://api.zedxe.com

Default product flow: the main site owns signup, billing, and plan assignment. Signed users later receive site-issued JWTs, while internal server traffic continues using the service key path.

Current canonical endpoints

GET

/v1/statements/:identifier

Canonical financial statement endpoint for annual, quarterly, normalized, and matrix output.

GET

/v1/regimes

Current adapter and regime status so the site can explain what is live, limited, or pending.

GET

/v1/auth/status

Plan-aware auth inspection endpoint for dashboards, quota display, and upgrade messaging.

Quick start

curl "https://api.zedxe.com/v1/statements/AAPL?regime=sec_edgar&statement=income_statement&frequency=annual&format=normalized&periods=5" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN"

const response = await fetch(
  "https://api.zedxe.com/v1/statements/AAPL?regime=sec_edgar&statement=income_statement&frequency=annual&format=normalized",
  {
    headers: {
      Authorization: `Bearer ${siteToken}`
    },
    cache: "no-store"
  }
);

const payload = await response.json();
const plan = response.headers.get("x-zapi-plan");
const remaining = response.headers.get("x-ratelimit-remaining");

Rate-limit headers exposed on responses

x-zapi-plan

Resolved plan id for the current request.

x-ratelimit-limit

Current hourly cap for the active plan.

x-ratelimit-remaining

Requests remaining in the current rolling hour bucket.

x-ratelimit-reset

ISO timestamp for the next quota reset.

Authentication

Free plan access

The intended starter tier is the Free plan: US data only, last 5 years of history, and a strict rate limit to prevent abuse.

Bearer JWT for signed plans

The site backend will mint HS256 JWTs with at least sub, plan, iss, aud, and exp. Until billing is wired, the main site can still map users into Free, Plus, and Pro through site config and keep Zapi enforcement unchanged.

Service key for server traffic

Internal site services keep using x-zapi-api-key. In the main app this maps to ZAPI_INTERNAL_API_KEY.

Current site environment target

ZAPI_BASE_URL=https://api.zedxe.com
ZAPI_INTERNAL_API_KEY=<same service key as Zapi>
ZAPI_JWT_ISSUER=zedxe
ZAPI_JWT_AUDIENCE=zapi-api
ZAPI_DEFAULT_SIGNED_PLAN=free
ZAPI_PLUS_EMAILS=analyst@company.com
ZAPI_PRO_EMAILS=owner@company.com

Statement query model

regimesec_edgar | companies_house | edinet | india_placeholder

Selects the filing regime and is gated by the active user plan.

statementincome_statement | balance_sheet | cash_flow

Chooses the canonical statement family.

frequencyannual | quarterly

Quarterly requests can optionally append TTM where the economics are valid.

viewrestated | as_reported

Restated is the default. As-reported preserves the original filing view when revisions exist.

formatnormalized | matrix

Normalized is best for product logic. Matrix is best for statement table rendering.

periods1-20

The request can ask for more periods than are returned when upstream history is incomplete.

includeTtmtrue | false

Adds TTM for eligible quarterly duration statements. Annual requests do not emit TTM proxies.

debugtrue | false

When true, the normalized response includes canonical fact traces under debug.facts.

Endpoint notes

GET /v1/statements/:identifier

Use this for annual and quarterly statements. Normalized format is the right source for charts, analytics, and reusable site-side rendering logic.

GET /v1/regimes

Surface adapter status in the product UI so users can see what is live, parser-limited, or pending before they hit unsupported requests.

GET /v1/auth/status

Best for the future signed-in API dashboard because it returns plan, remaining quota, feature flags, and allowed regimes in one response.

History behavior

Requested periods can exceed returned periods. Check meta.requestedPeriods, meta.returnedPeriods, meta.historyCoverage, and meta.historyNote before assuming full depth outside mature SEC coverage.

Normalized format

Contract shape: meta, columns, rows, and periods, with optional debug.facts when debug=true.

{
  "meta": {
    "ticker": "AAPL",
    "companyName": "Apple Inc.",
    "statement": "income_statement",
    "frequency": "annual",
    "view": "restated",
    "currency": "USD",
    "fiscalYearEnd": "Sep 30",
    "titleSlug": "AAPL_income-statement_Annual_Restated",
    "sourceRegime": "sec_edgar",
    "requestedPeriods": 3,
    "returnedPeriods": 3,
    "historyCoverage": "full",
    "qualityFlags": []
  },
  "columns": ["2023", "2024", "2025"],
  "rows": [
    {
      "metricCode": "gross_profit",
      "label": "Gross Profit",
      "depth": 0,
      "unit": "USD",
      "rowKind": "metric",
      "values": [169148000000, 180683000000, 195036000000],
      "qualityFlags": []
    }
  ],
  "periods": {
    "2025": {
      "revenue_total": 416161000000,
      "eps_diluted": 7.46
    }
  }
}

Matrix format

Contract shape: workbook-style rows with display_values, display scale metadata, and a footer for table exports.

{
  "meta": {
    "ticker": "AAPL",
    "statement": "income_statement",
    "frequency": "annual",
    "view": "restated",
    "currency": "USD",
    "fiscalYearEnd": "Sep 30",
    "titleSlug": "AAPL_income-statement_Annual_Restated",
    "requestedPeriods": 3,
    "returnedPeriods": 3,
    "historyCoverage": "full",
    "displayScale": "thousands_when_large",
    "negativeStyle": "parentheses"
  },
  "columns": ["2023", "2024", "2025"],
  "rows": [
    {
      "metric_code": "revenue_total",
      "label": "Total Revenue",
      "depth": 1,
      "row_kind": "metric",
      "unit": "USD",
      "values": [383285000000, 391035000000, 416161000000],
      "display_values": ["383,285,000", "391,035,000", "416,161,000"]
    }
  ],
  "footer": "Fiscal year ends in Sep 30 | USD"
}

Coverage notes

Document the caveats where users will see them

Request access

United StatesLive

sec_edgar

Free, Plus, and Pro

Official SEC statements are the production baseline, including restated and as-reported views.

United KingdomLimited

companies_house

Pro when parser coverage is ready

Companies House auth is live, but full filing-level parser coverage is still being completed.

IndiaLimited

india_placeholder

Pro as broader parser coverage comes online

Official annual coverage is live. Quarterly and TTM depth still depends on broader parser work.

JapanPending

edinet

Pro once the EDINET key is available

Official EDINET parsing is pending the production key, so Japan is not yet fully available on the live site flow.