{"openapi":"3.1.0","info":{"title":"Registrum API","description":"\n# Registrum API\n\nUK company intelligence - structured financials, director networks, and intelligent caching - from a single developer-friendly REST API.\n\n---\n\n## Quick Start\n\n### 1. Get your API key\n\nSign up to receive your API key.\n\n### 2. Authenticate your requests\n\nInclude your API key in the **`X-API-Key`** header with every request:\n\n```\nX-API-Key: reg_live_your_key_here\n```\n\n> **Using the interactive docs below?** Click the green **Authorize** button at the top of this page, paste your API key, and click **Authorize**. All subsequent \"Try it out\" requests will include it automatically.\n\n### 3. Make your first request\n\nSearch for a company:\n```\nGET /v1/search?q=tesco\n```\n\nGet an enriched company profile:\n```\nGET /v1/company/00445790\n```\n\n## Client libraries & examples\n\n- **Python**: [companies-house-api-python-starter](https://github.com/RegistrumUK/companies-house-api-python-starter) - auth, rate-limit backoff, pagination, and the iXBRL-vs-PDF gotcha, in one file\n- **Node.js**: [companies-house-api-node-starter](https://github.com/RegistrumUK/companies-house-api-node-starter) - same, using the built-in `fetch`\n- **MCP (Claude, Cursor)**: [registrum-mcp](https://github.com/RegistrumUK/uk-companies-house-mcp) server, with a [prompt cookbook and example scripts](https://github.com/RegistrumUK/registrum-mcp-examples)\n\n---\n\n## How It Works\n\nThis API sits on top of the [Companies House public API](https://developer.company-information.service.gov.uk/) and adds:\n\n- **Intelligent caching** - responses are cached so repeat queries are instant and you never hit rate limits\n- **Enriched profiles** - company age, accounts status, size classification, and more in a single call\n- **Director networks** - discover all companies connected through shared directors\n- **Structured financials** - parsed iXBRL filings returned as clean JSON with current + prior year\n\n## Upstream Call Costs & Throughput\n\nEach endpoint makes a different number of calls to the Companies House API on your behalf.\n**Cached responses cost nothing** - once a company is fetched, repeat requests within the cache window are instant.\n\n| Endpoint | Upstream calls (cold cache) | Cache duration |\n|---|---|---|\n| `GET /v1/search` | 1 per unique query | 1 hour |\n| `GET /v1/company/{n}` | 1 per company | 30 days |\n| `GET /v1/company/{n}/directors` | ~N+2 (N = number of directors) | 30 days |\n| `GET /v1/company/{n}/network?depth=1` | ~N+2 | 30 days |\n| `GET /v1/company/{n}/network?depth=2` | 50–200 (capped at 30 connected companies) | 30 days |\n| `GET /v1/company/{n}/financials` | 2–3 (filing history + doc metadata + iXBRL download) | 90 days |\n| `GET /v1/health` | 0 | - |\n| `GET /v1/health/deep` | 1 | - |\n| `GET /v1/health/probes` | 0 | - |\n\n**Safe throughput on cold cache (approximate, across all customers):**\n- Search and company profiles: up to ~100 unique queries per minute\n- Directors and network (depth=1): up to ~8 different companies per minute\n- Network (depth=2): up to ~2–3 different companies per 5 minutes\n\nIf these rates are exceeded, responses slow briefly (typically 5–15 seconds) while upstream capacity\nrecovers - you won't receive errors, just slightly higher latency. The cache eliminates this concern\nfor any company queried more than once within the cache window.\n\n## Response Format\n\nEvery endpoint returns responses in this standard format:\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": { ... },\n  \"cached\": true,\n  \"cache_age_seconds\": 3421,\n  \"credits_used\": 1,\n  \"credits_remaining\": 487\n}\n```\n\n## Response Headers\n\nEvery response includes:\n- `X-Request-Id` - unique ID for this request (useful for debugging/support)\n- `X-API-Version` - current API version\n- `X-Data-Stale: true` - only present when serving expired cache during an upstream outage\n\n## Rate Limits\n\nEvery new key gets full access for its first 60 days - no monthly quota, every endpoint - then moves to Free. Live values: `GET /v1/plans`.\n\n| Tier | Price | Calls/month | Calls/day | Burst |\n|------|-------|-------------|-----------|-------|\n| Free | Free | 50 | 15 | 10/min |\n| Web | £9/mo | 500 | 50 | 30/min |\n| Pro | £49/mo | 4,000 | 400 | 100/min |\n| Enterprise | On request | Unlimited | Unlimited | 150/min |\n\n**Pro/Enterprise-only features:** `network?depth=2`, PSC chain traversal, and ECCTA compliance monitoring.\nFree/Web requests to these return `403 PLAN_REQUIRED` with an `upgrade_url`.\n\n## Errors\n\nErrors return a JSON object with `status: \"error\"` and a human-readable `detail` message:\n\n```json\n{\n  \"status\": \"error\",\n  \"detail\": \"Company 99999999 not found\",\n  \"request_id\": \"a1b2c3d4-...\"\n}\n```\n\n| Status Code | Meaning |\n|-------------|---------|\n| 400 | Invalid input (e.g., bad company number format) |\n| 401 | Missing or invalid API key |\n| 404 | Company not found |\n| 422 | Validation error (e.g., search query too long) |\n| 429 | Rate limit exceeded |\n| 502 | Companies House API is temporarily unavailable |\n| 500 | Unexpected server error |\n\n## Usage Dashboard\n\nTrack your API calls, quota, and reset date at **[registrum.co.uk/dashboard](https://registrum.co.uk/dashboard)**.\nSign in with the email you used to get your key - no password needed.\n\nOr call `GET /v1/usage` (free, no credit consumed) to read quota programmatically.\n\n## Need Help?\n\nInclude the `X-Request-Id` from your response headers when contacting support - it helps us trace exactly what happened.","version":"0.1.0"},"servers":[{"url":"https://api.registrum.co.uk","description":"Production"}],"paths":{}}