API Reference

Complete reference for the Perpetua v1 REST API. All endpoints return JSON.

Base URL: https://api.perpetua.ukVersion: v1Format: JSON

Authentication

Pass your API key via the X-API-Key header on every request. Get a key →

curl -H "X-API-Key: pk_live_your_key_here" \
  https://api.perpetua.uk/v1/companies/00445790

Rate Limits

Rate limits apply per API key. Developer tier: 10 req/min, 1,000/month. Higher tiers available on request. View plans →

Endpoints

The Perpetua v1 API exposes 10 company endpoints plus 8 lender intelligence endpoints backed by canonical UK lender entities and the ``mv_lender_stats`` materialized view.

GET/v1/companies/search/

Search Companies

Filter by SIC code, revenue range, employee count, location, data quality tier, and more.

POST/v1/companies/compare

Compare Companies

Side-by-side comparison of up to 10 companies across enrichment dimensions.

GET/v1/companies/{number}

Company Profile

Full company profile with financials, ownership, constraints, and quality signals.

GET/v1/companies/{number}/financials

Financial History

Multi-year XBRL financial history. Balance-sheet fields are broadest; revenue, profit, cash-flow, and liquidity metrics depend on filing type.

GET/v1/companies/{number}/time-series

Financial Time-Series

Trend summaries and arrays for reported metrics across filing years. Coverage is materially deeper on full accounts than abridged filings.

GET/v1/companies/{number}/ownership

Ownership Intelligence

PSC beneficial owners, age estimation, and corporate ownership structure.

GET/v1/companies/{number}/ownership-graph

Ownership Graph

PSC-to-management graph for group structure traversal.

GET/v1/companies/{number}/constraints

Deal Constraints

Flags secured lending constraints such as floating/fixed charges and unsatisfied encumbrances.

GET/v1/companies/{number}/explain

Provenance Explain

Returns filing URL, chosen XBRL tags, and extraction confidence for key metrics.

GET/v1/companies/{number}/deal-snapshot

Deal Snapshot

Single-call buyability summary combining owner, financial, and constraint signals.

GET/v1/lenders

Lender League Table

Paginated list of canonical UK lenders ranked by charge activity. Filter by classification (bank, challenger_bank, building_society, specialist_mortgage, private_credit, asset_finance, invoice_finance, …), activity window, minimum charge count, or free-text name match. Pass ?include=series for 24-month sparkline data.

GET/v1/lenders/{id}

Lender Profile

Canonical lender with parent/subsidiary structure, raw alias list, and aggregate charge stats (totals + recent activity).

GET/v1/lenders/{id}/portfolio

Lender Portfolio

Paginated companies with charges from this lender, with per-company aggregated counts. Filter by charge status (outstanding | satisfied | all).

GET/v1/lenders/{id}/activity

Lender Monthly Activity

Monthly new + satisfied charge counts, oldest first. ?months=1..60 controls the trailing window (default 24). Months with no activity are omitted.

GET/v1/lenders/{id}/sectors

Lender Sector Breakdown

Top-15 SIC-section breakdown of companies this lender has charges against, ranked by charge count.

GET/v1/lenders/{id}/regions

Lender Regional Breakdown

UK ITL1 regional breakdown of companies this lender has charges against.

GET/v1/lenders/{id}/size-breakdown

Lender Size Breakdown

Revenue-band breakdown of companies this lender has charges against, ordered by band threshold. The ``Unknown`` band covers companies without a resolved latest_revenue.

GET/v1/lenders/{id}/instruments

Lender Instrument Mix

Top-5 charge-type instruments this lender uses (fixed charge, debenture, floating charge, mortgage, …), ordered by charge count.

Try it live

Interactive API Explorer

Try core endpoints through a safe proxy with demo credentials.

cURL

Auto-updated
curl -H "X-API-Key: <your_api_key>" \
  "${PERPETUA_API_URL:-http://localhost:8000}/v1/companies/00445790"
HTTP -

Response JSON

{}

Errors

Perpetua uses standard HTTP status codes.

200OK — request succeeded.
401Unauthorized — missing or invalid API key.
404Not found — company number not in dataset.
429Too Many Requests — rate limit exceeded.

Code Examples

cURL

curl -H "X-API-Key: pk_live_your_key_here" \
  https://api.perpetua.uk/v1/companies/12345678

Python

import requests

resp = requests.get(
    "https://api.perpetua.uk/v1/companies/12345678",
    headers={"X-API-Key": "pk_live_your_key_here"}
)
company = resp.json()
print(company["name"], company["data_quality_tier"])

JavaScript

const resp = await fetch(
  "https://api.perpetua.uk/v1/companies/12345678",
  { headers: { "X-API-Key": "pk_live_your_key_here" } }
);
const company = await resp.json();
console.debug(company.name, company.data_quality_tier);

Lender Intelligence

Canonical UK lender entities with charge aggregates, sector / region / size breakdowns, 24-month activity series, and instrument-mix stats. The league table is backed by ``mv_lender_stats`` (refreshed by the charge-ingest pipeline); detail endpoints query the ``company_charges`` flat table + per-lender RPCs. Filter the league table with ?classification= using any of the canonical values: bank, challenger_bank, building_society, specialist_mortgage, private_credit, asset_finance, invoice_finance, hmrc, government, director_loan, trade_creditor, other, unknown.

cURL

curl -H "X-API-Key: pk_live_your_key_here" \
  "https://api.perpetua.uk/v1/lenders?classification=specialist_mortgage&limit=15"

Python

import requests

resp = requests.get(
    "https://api.perpetua.uk/v1/lenders",
    headers={"X-API-Key": "pk_live_your_key_here"},
    params={"classification": "specialist_mortgage", "limit": 15, "include": "series"},
)
league = resp.json()
for row in league["data"]:
    print(row["display_name"], row["outstanding_charges"])

JavaScript

const resp = await fetch(
  "https://api.perpetua.uk/v1/lenders?classification=specialist_mortgage&limit=15&include=series",
  { headers: { "X-API-Key": "pk_live_your_key_here" } }
);
const { data } = await resp.json();
for (const row of data) {
  console.debug(row.display_name, row.outstanding_charges);
}