HTTP API

Quick start

Free tier — 30 req/min per user. Grab a token from /account.

$ curl https://openregistry.sophymarine.com/api/v1/companies/GB/00185647     -H 'Authorization: Bearer or_pat_…'
{
  "queried_at": "2026-05-17T12:30:00+01:00 (Europe/London)",
  "jurisdiction": "GB",
  "company_id": "00185647",
  "company_name": "J SAINSBURY PLC",
  "status": "active",
  "incorporation_date": "1922-11-10",
  "registered_address": "33 Charterhouse Street, London, EC1M 6HA",
  "jurisdiction_data": { ... }
}

The queried_at timestamp is when we hit the registry. The unified top-level fields are normalized across countries; the raw upstream payload comes back verbatim under jurisdiction_data so nothing is hidden.

Try it

Fires a real request from your browser against this server. No data leaves the page; nothing is logged differently than a normal API call.

// click Run query to fire

Two URL shapes, same dispatch

Pick whichever fits your client:

• REST (GET /api/v1/companies/{jur}/{id}/officers): resource-oriented, matches OpenCorporates / Companies House conventions, easy to cache, easy to read in URL bars.
• RPC (GET|POST /api/v1/rpc/{tool}): one endpoint per tool, 1:1 with the MCP surface, takes arguments in query string or JSON body. Best when you're generating calls programmatically.

Both routes share the same auth, the same rate limits, and the same response envelope. Pick one per project; mixing is fine.

REST endpoints

Common workflow: search → profile → officers → filings → document

$ B=https://openregistry.sophymarine.com
$ T='Authorization: Bearer or_pat_…'   # /account

# 1. Find the company by name
$ curl -H "$T" "$B/api/v1/companies?q=sainsbury&jurisdiction=GB&limit=2"

# 2. Pull the profile by the registry ID
$ curl -H "$T" "$B/api/v1/companies/GB/00185647"

# 3. Pull officers + shareholders + recent filings
$ curl -H "$T" "$B/api/v1/companies/GB/00185647/officers"
$ curl -H "$T" "$B/api/v1/companies/GB/00185647/shareholders"
$ curl -H "$T" "$B/api/v1/companies/GB/00185647/filings?limit=10"

# 4. Download a specific filing PDF
$ curl -H "$T" -o accounts.pdf \
    "$B/api/v1/documents/GB/<document_id_from_step_3>/content?max_bytes=20000000"

RPC endpoints

One endpoint per MCP tool. Pass arguments as query parameters on GET, or a JSON body on POST.

# GET form — args in query string
$ curl -H 'Authorization: Bearer or_pat_…' \
    "https://openregistry.sophymarine.com/api/v1/rpc/search_companies?jurisdiction=NO&query=equinor&limit=2"

# POST form — args in JSON body
$ curl -X POST https://openregistry.sophymarine.com/api/v1/rpc/get_officers \
    -H 'Authorization: Bearer or_pat_…' \
    -H 'Content-Type: application/json' \
    -d '{"jurisdiction":"GB","company_id":"00185647"}'

Per-tool argument schemas: see /docs for each tool's input fields.

Authentication

Two modes, both supported on every endpoint:

• Personal Access Token (Authorization: Bearer or_pat_…) — recommended for scripts and server-to-server use. Generate one at /account → "API tokens" with a chosen TTL (7d / 30d / 90d / 1y / never). Token is shown exactly once at creation, then only the prefix is visible. Revocation is immediate. This is the curl-friendly auth path.
• OAuth Bearer JWT (Authorization: Bearer eyJ…): for MCP-style clients that already implement the OAuth 2.1 flow (Claude Desktop, Cursor, etc.). 15-minute access token + 30-day refresh. See OAuth discovery. Authenticated callers get a tier-keyed per-user rate-limit bucket and higher fan-out cap (Pro=10 / Max=30 / Enterprise=unlimited).

Invalid tokens get 401 with a WWW-Authenticate hint.

Tier-redaction strips a small set of source-URL fields below Enterprise; the underlying company data (jurisdiction_data) is identical across tiers. We do not modify or summarise the registry's payload.

# Personal Access Token (your tier's per-user rate limit)
$ curl https://openregistry.sophymarine.com/api/v1/companies/GB/00185647 \
    -H 'Authorization: Bearer or_pat_AbCdEf...wxyz'

Rate limits

Per-country caps are shared across all tiers — that's our commitment to the upstream registries. Hitting one returns 429 with Retry-After. The per-tier limits are on top: an Enterprise user gets 3000 rpm total, distributed however they want across countries.

Error envelope

Every error response is JSON with a stable shape:

{
  "error": "rate_limit_exceeded",
  "message": "Per-user rate limit (30 rpm) exceeded. Retry in 12s.",
  "retry_after_seconds": 12,
  "tier": "free"
}

CORS & client conventions

All routes return Access-Control-Allow-Origin: *. Use directly from the browser, server-side, or any HTTP client.

Tips:

• Pagination: limit (default 25, max 1000 depending on tool) and cursor or offset depending on the country. See /docs per tool.
• Cache busting: ?fresh=true bypasses the in-process cross-call cache and hits the upstream registry directly.
• Path wins over query: /api/v1/companies/GB/00185647?jurisdiction=NO treats jurisdiction=GB from the URL path; the query string is ignored.

See also

• /docs — full tool reference with per-tool argument schemas and per-country quirks.
• /mcp — same tools exposed as a Model Context Protocol server for Claude, Cursor, and other AI clients.
• /account → "API tokens" — generate a Personal Access Token for scripts.
• OAuth discovery — for the Bearer JWT flow (MCP clients).
• GitHub — open-source MCP stdio bridge (no source code for the API surface itself).