ORSF API knowledge base

Overview

ORSF (Otvorený register slovenských firiem — Open Register of Slovak Companies) aggregates 14 Slovak state registers into a single REST API and a queryable dataset. Three access modes:

• REST API — JSON over HTTPS, anonymous read on public endpoints
• MCP server — for AI agents (Claude, Cursor, Zed); one-line install
• CLI — npx @orsf/cli for shell-based exploration

All data is sourced from official public registers and carries lineage (source + fetchedAt per record). License: CC-BY 4.0 — attribute ORSF in your application.

60-second quickstart

Three commands, no auth, no keys.

curl https://api.orsf.sk/v1/companies/55609830

curl 'https://api.orsf.sk/v1/search?q=8888'

curl https://api.orsf.sk/v1/stats/summary

Want to try without leaving this page? Jump to the Live playground.

Authentication

Most endpoints are public. Authentication is required only for person-level data and write actions:

Sign in via POST /api/auth/sign-in/email. Server returns a session cookie:

Set-Cookie: __Secure-orsf.session_token=...; Path=/; HttpOnly; Secure; SameSite=Lax

Pass the cookie on subsequent requests. There are no API keys or bearer tokens currently — sessions are the only auth method.

Endpoints

Full reference. See OpenAPI 3.1 spec for the machine-readable form.

GET /v1/searchpublic

Fulltext search over company names + IČO fast-path (numeric query → direct lookup).

curl 'https://api.orsf.sk/v1/search?q=poistovna&register=Obchodný%20register&limit=5'

GET /v1/companies/{ico}public

Full company record — identity, address, financial statements, business activities, VAT registration.

roles array is empty for anonymous (rolesLocked: true); sign in to see directors/officers.

curl https://api.orsf.sk/v1/companies/55609830 | jq '.name, .nationalId, .statusCode'

GET /v1/companies/{ico}/graphauth

Connection graph (Sigma.js / graphology compatible). Nodes + edges for company ↔ persons ↔ other companies. Depth 1-3.

GET /v1/persons/{id}auth

Person record with all known company roles. id is internal UUID returned from /v1/companies/{ico}.roles[].person.id.

GET /v1/stats/summarypublic

Aggregate counts (companies, filings, persons). Cached 5 min, approximate counts (within ~5%).

GET /v1/stats/districtspublic

Companies per NUTS LAU1 district. ?includeAll=true to include sole traders + non-business orgs.

GET /v1/labels?locale=en|skpublic

Localized human labels for enum codes. Fetch once at app startup, cache. Returns:

{
  "locale": "en",
  "status": { "active": "Active", "dissolved": "Dissolved", ... },
  "register": { "commercial": "Commercial Register", ... },
  "kind": { "company": "Company", "sole_trader": "Sole trader", "other": "Other" }
}

Field naming

Every Slovak field name in our responses has an English canonical alias. New clients should use the English form; legacy Slovak names will work forever. Full convention at docs/api-conventions.md.

Enum codes

Enum-like fields expose three forms: raw (from source), xxxCode (stable English machine code), and a localizable label via /v1/labels.

statusCode

registerCode

Errors

JSON error shape (Fastify default + our additions):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Company with ID 12345678 not found."
}

Common status codes

Rate limits

Need higher limits for legitimate bulk use? Email [email protected].

MCP server (for AI agents)

The Model Context Protocol server exposes ORSF as tool-calls for LLM agents. Works with Claude Code, Claude Desktop, Cursor, Continue, Windsurf, and any MCP-compatible client.

Claude Code

claude mcp add orsf -- npx -y @orsf/mcp-server

Claude Desktop / Cursor / Windsurf

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or platform equivalent):

{
  "mcpServers": {
    "orsf": {
      "command": "npx",
      "args": ["-y", "@orsf/mcp-server"]
    }
  }
}

Available tools

• search_companies — fulltext + filters
• get_company — full record by IČO
• get_company_graph — connection graph
• get_person — by UUID (auth required)
• get_person_graph — person-centric graph (auth required)
• get_stats — aggregate counters

MCP server is open-source on GitHub. Runs locally; never sends prompts to any third party — only ORSF JSON API.

CLI tool

Shell-based access without writing code:

npx @orsf/cli search "poistovna"
npx @orsf/cli company 55609830
npx @orsf/cli graph 55609830 --depth 2

Same data as REST API. Output is pretty-printed JSON or table form (with --format=table).

Pagination

List endpoints support limit + offset (offset-based pagination).

# First page
curl 'https://api.orsf.sk/v1/search?q=sro&limit=20&offset=0'

# Next page
curl 'https://api.orsf.sk/v1/search?q=sro&limit=20&offset=20'

Maximum offset is 1000 — for deeper paginations, narrow the search with filters (region, year, legal form). Cursor-based pagination is on the roadmap for larger datasets.

Versioning

URL-based versioning (/v1/...). Breaking changes will introduce/v2/... with a long overlap window. Field aliases (e.g., ico → nationalId) are added next to legacy keys and never remove the old form.

Subscribe to changes:

• Watch the GitHub repo
• OpenAPI spec is the source of truth — diff /v1/openapi.json over time

Status & SLA

Live status: status.orsf.sk. ORSF is a beta service — best-effort availability, no SLA. For production use cases requiring an SLA, contact us.

Issues, feature requests, abuse reports: [email protected].

Glossary

IČO

Identifikačné číslo organizácie — 8-digit company national ID, used in SK and CZ.

DIČ

Daňové identifikačné číslo — tax identification number.

IČ DPH / VAT ID

VAT registration ID, prefixed with country code (e.g., SK2122034970).

RPO

Register právnických osôb — Register of Legal Entities (Statistical Office of SR).

RUZ

Register účtovných závierok — Register of Financial Statements (Ministry of Finance).

ORSR

Obchodný register SR — Slovak Commercial Register (Ministry of Justice).

ZRSR

Živnostenský register — Trade Register (Ministry of Interior).

NUTS

Nomenclature of Territorial Units for Statistics. ORSF uses NUTS-3 (regionCode) and LAU1 (districtCode).