{ "openapi": "3.0.3", "info": { "title": "Latvian Business Registry API", "description": "API for Latvian company data, financials, ownership, risk assessment, and sanctions screening.", "version": "1.0.0" }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "X-API-Key", "in": "header" }, "session": { "type": "apiKey", "name": "izluks-session", "in": "cookie" } }, "schemas": {} }, "paths": { "/api/v1/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "tags": [ "System" ], "description": "Verifies the API process is reachable and both the primary registry database and auth database accept queries. Returns `status: ok` when both succeed; `status: degraded` with HTTP 503 when either fails. Public — no authentication required.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "status", "db" ], "properties": { "status": { "type": "string" }, "db": { "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "status", "db" ], "properties": { "status": { "type": "string" }, "db": { "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/companies/search": { "get": { "operationId": "searchCompanies", "summary": "Search companies by name", "tags": [ "Companies" ], "description": "Full-text search across the Latvian Business Registry by company name. Supports filters for entity type, activity status, region, and registration date range. Results ranked by trigram similarity on the name.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Search query" }, { "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum results to return" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Entity type filter (SIA, AS, etc.)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "activeOnly", "required": false, "description": "Only return active companies" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "region", "required": false, "description": "Filter by region" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from", "required": false, "description": "Registered after date (YYYY-MM-DD)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to", "required": false, "description": "Registered before date (YYYY-MM-DD)" }, { "schema": { "maxLength": 50, "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Company status filter" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/find/presets": { "get": { "operationId": "listFindPresets", "summary": "List company find presets", "tags": [ "Companies" ], "description": "Return the catalog of named filter bundles accepted by `GET /companies/find?preset=…`. Each preset is a curated, reusable filter set (e.g. 'dormant-small-cap', 'high-revenue-growth') maintained server-side. Cached for one hour.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/companies/find": { "get": { "operationId": "findCompanies", "summary": "Find companies by advanced filters", "tags": [ "Companies" ], "description": "Rich filter search across the registry with pagination. Filter on registration status, region, revenue, profit, assets, equity, employee counts, officer/shareholder/UBO name, and flags for insolvency, liquidation, suspension, or sanctions (each tri-state: `true` filters companies with the flag, `false` filters those without). The `activity` filter accepts a NACE code (section letter `K`, division `46`, group `46.1`, or class `46.18`) or free-form description text in Latvian or English; text input falls back to the legacy registry activity description column. Each result row exposes `naceCode` and `naceText` (description language follows the `locale` query param, default `lv`). Pass `preset=` to layer on a server-side filter bundle. At least one filter is required.", "parameters": [ { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "name", "required": false, "description": "Company name filter" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Entity type filter (comma-separated)" }, { "schema": { "maxLength": 50, "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Company status filter" }, { "schema": { "type": "boolean" }, "in": "query", "name": "activeOnly", "required": false, "description": "Only return active companies" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "region", "required": false, "description": "Filter by region" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "registeredFrom", "required": false, "description": "Registered after date (YYYY-MM-DD)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "registeredTo", "required": false, "description": "Registered before date (YYYY-MM-DD)" }, { "schema": { "type": "number" }, "in": "query", "name": "revenueMin", "required": false, "description": "Minimum revenue (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "revenueMax", "required": false, "description": "Maximum revenue (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "profitMin", "required": false, "description": "Minimum profit (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "profitMax", "required": false, "description": "Maximum profit (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "assetsMin", "required": false, "description": "Minimum total assets (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "assetsMax", "required": false, "description": "Maximum total assets (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "equityMin", "required": false, "description": "Minimum equity (EUR)" }, { "schema": { "type": "number" }, "in": "query", "name": "equityMax", "required": false, "description": "Maximum equity (EUR)" }, { "schema": { "type": "integer" }, "in": "query", "name": "employeesMin", "required": false, "description": "Minimum employee count" }, { "schema": { "type": "integer" }, "in": "query", "name": "employeesMax", "required": false, "description": "Maximum employee count" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "official", "required": false, "description": "Filter by official/board member name" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "shareholder", "required": false, "description": "Filter by shareholder name" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "ubo", "required": false, "description": "Filter by ultimate beneficial owner" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "activity", "required": false, "description": "Filter by NACE code (section letter `K`, division `46`, group `46.1`, or class `46.18`) or by description text (Latvian or English). Text input also falls back to the legacy registry activity description." }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasInsolvency", "required": false, "description": "Tri-state. `true` = has insolvency proceedings; `false` = does not have insolvency proceedings; omit to leave unfiltered." }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasLiquidation", "required": false, "description": "Tri-state. `true` = has liquidation proceedings; `false` = does not; omit to leave unfiltered." }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasSuspension", "required": false, "description": "Tri-state. `true` = has VID tax suspension; `false` = does not; omit to leave unfiltered." }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasSanctions", "required": false, "description": "Tri-state. `true` = has sanctions matches; `false` = no sanctions matches; omit to leave unfiltered." }, { "schema": { "enum": [ "name", "registered", "revenue", "profit", "assets", "equity", "employees" ], "type": "string" }, "in": "query", "name": "sort", "required": false, "description": "Sort field" }, { "schema": { "type": "boolean" }, "in": "query", "name": "desc", "required": false, "description": "Sort descending" }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "columns", "required": false, "description": "Columns to include (comma-separated)" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "preset", "required": false, "description": "Named search preset" }, { "schema": { "type": "boolean" }, "in": "query", "name": "count", "required": false, "description": "Return only count, not results" }, { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Results per page" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "enum": [ "lv", "en" ], "type": "string" }, "in": "query", "name": "locale", "required": false, "description": "Language for `naceText` in result rows (default: `lv`)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/match": { "get": { "operationId": "matchCompany", "summary": "Fuzzy match a company name", "tags": [ "Companies" ], "description": "Reconciliation endpoint for matching unstructured company names (e.g. from invoices, contracts) to registry records. Returns ranked candidates with match scores and confidence signals. Use for entity resolution in data ingestion pipelines.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Entity name to match" }, { "schema": { "minimum": 1, "maximum": 50, "default": 5, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum candidates to return" }, { "schema": { "minimum": 0, "maximum": 1, "type": "number" }, "in": "query", "name": "threshold", "required": false, "description": "Minimum similarity score (0-1)" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/batch": { "post": { "operationId": "batchLookupCompanies", "summary": "Batch lookup by regcode", "tags": [ "Companies" ], "description": "Resolve a set of registration codes to their minimal company records in one call. Unknown regcodes are returned as `null` entries rather than producing an error. Useful for bulk hydration of an external list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "regcodes" ], "properties": { "regcodes": { "minItems": 1, "maxItems": 100, "description": "List of registration codes", "type": "array", "items": { "pattern": "^[T]?\\d{8,11}$", "type": "string" } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/compare": { "post": { "operationId": "compareCompanies", "summary": "Compare companies side by side", "tags": [ "Companies" ], "description": "Side-by-side comparison of 2–5 companies on revenue, profit, equity, assets, employee counts, and derived ratios for a chosen financial year (default: latest available). Rate-limited to 10 requests per minute per caller.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "regcodes" ], "properties": { "regcodes": { "minItems": 2, "maxItems": 10, "description": "Registration codes to compare", "type": "array", "items": { "pattern": "^[T]?\\d{8,11}$", "type": "string" } }, "year": { "minimum": 1900, "maximum": 2100, "description": "Financial year to compare", "type": "integer" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}": { "get": { "operationId": "getCompanyByRegcode", "summary": "Get company profile", "tags": [ "Companies" ], "description": "Full dossier for a single company: core registry data, officers, shareholders, UBOs, recent financials, insolvency/liquidation/suspension history, and related flags. Response content is adjusted by the caller's tier — anonymous callers receive a reduced profile unless the regcode is on the free-access showcase list.", "parameters": [ { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/documents": { "get": { "operationId": "listCompanyDocuments", "summary": "List documents for a company", "tags": [ "Documents" ], "description": "Metadata catalog of annual reports and public-filing documents archived in UR's document system for this company. Download the bytes via `/companies/:regcode/documents/:docSource/:docId/download`.", "parameters": [ { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/documents/{docSource}/{docId}/download": { "get": { "operationId": "downloadCompanyDocument", "summary": "Download a company document", "tags": [ "Documents" ], "description": "Stream the raw document file from the UR archive. Content-Type varies by source (`application/pdf`, `image/tiff`, `application/vnd.etsi.asic-e+zip`, `application/edoc`). Rate-limited to 10/min. Paid tier only.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "regcode", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "docSource", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "docId", "required": true } ], "responses": { "200": { "description": "Document file (PDF/TIF/EDOC/ASICE)", "content": { "application/octet-stream": { "schema": { "description": "Binary payload", "type": "string" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/pledges": { "get": { "operationId": "listCompanyPledges", "summary": "List company pledges", "tags": [ "Pledges" ], "description": "Commercial pledges registered against a company's assets — pledge class, creditor, secured amount, effective date. Recent pledges may indicate financing activity or stress.", "parameters": [ { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/financials": { "get": { "operationId": "getFinancialHistory", "summary": "Financial statement history", "tags": [ "Financials" ], "description": "Historical annual reports for a company: revenue, profit, balance sheet items, and cash flow components, sorted newest-first. Anonymous callers receive only the most recent year; authenticated callers get up to 5 years (or all available).", "parameters": [ { "schema": { "minimum": 1, "maximum": 20, "default": 5, "type": "integer" }, "in": "query", "name": "years", "required": false, "description": "Number of years of history" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/ratios": { "get": { "operationId": "getFinancialRatios", "summary": "Financial ratios", "tags": [ "Financials" ], "description": "Computed ratios (current ratio, debt-to-equity, return on assets, return on equity, gross margin, net margin, and more) for up to 5 historical years. Null when a ratio's underlying inputs are missing.", "parameters": [ { "schema": { "minimum": 1, "maximum": 20, "default": 5, "type": "integer" }, "in": "query", "name": "years", "required": false, "description": "Number of years of history" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/benchmark": { "get": { "operationId": "getSectorBenchmark", "summary": "Sector benchmark", "tags": [ "Financials" ], "description": "Position the company's financials against same-NACE-sector peers for a chosen year — percentile rank on revenue, profit, assets, equity, employee count. Defaults to the most recent year with broad sector coverage.", "parameters": [ { "schema": { "minimum": 1900, "maximum": 2100, "type": "integer" }, "in": "query", "name": "year", "required": false, "description": "Financial year to benchmark" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/peers": { "get": { "operationId": "getCompanyPeers", "summary": "Peer companies", "tags": [ "Financials" ], "description": "Identify peer companies in the same NACE sector with similar revenue/asset scale. Returns up to `limit` peers ranked by similarity.", "parameters": [ { "schema": { "minimum": 1, "maximum": 50, "default": 10, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum peers to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/top": { "get": { "operationId": "getTopCompanies", "summary": "Top companies by metric", "tags": [ "Financials" ], "description": "Registry-wide ranking of companies by a chosen financial metric (`revenue`, `profit`, `assets`, or `equity`) for a given year. Anonymous callers see a truncated list; authenticated callers see the full requested `limit`.", "parameters": [ { "schema": { "enum": [ "revenue", "profit", "assets", "equity", "employees" ], "default": "revenue", "type": "string" }, "in": "query", "name": "metric", "required": false, "description": "Ranking metric" }, { "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum results to return" }, { "schema": { "minimum": 1900, "maximum": 2100, "type": "integer" }, "in": "query", "name": "year", "required": false, "description": "Financial year" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/owners": { "get": { "operationId": "getUpstreamOwners", "summary": "Upstream ownership tree", "tags": [ "Ownership" ], "description": "Traverse the ownership graph upward from a company to its ultimate beneficial owners. Depth is capped by tier: anonymous callers see direct owners only, free sees 3 levels, paid sees up to 10.", "parameters": [ { "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "integer" }, "in": "query", "name": "depth", "required": false, "description": "Maximum traversal depth" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/holdings": { "get": { "operationId": "getDownstreamHoldings", "summary": "Downstream holdings tree", "tags": [ "Ownership" ], "description": "Traverse the ownership graph downward from a company to the subsidiaries and investments it controls. Depth is capped the same way as the upstream tree.", "parameters": [ { "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "integer" }, "in": "query", "name": "depth", "required": false, "description": "Maximum traversal depth" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/ownership/chain": { "get": { "operationId": "getOwnershipChain", "summary": "Ownership chain between entities", "tags": [ "Ownership" ], "description": "Find the shortest chain of ownership connecting two entities (companies or persons). Returns a null result if no chain exists within `depth`. Paid tier only.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "from", "required": true, "description": "Source entity (regcode or name)" }, { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "to", "required": true, "description": "Target entity (regcode or name)" }, { "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "integer" }, "in": "query", "name": "depth", "required": false, "description": "Maximum chain length" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/ownership-history": { "get": { "operationId": "getOwnershipHistory", "summary": "Ownership change history", "tags": [ "Ownership" ], "description": "Chronological record of shareholder and beneficial-owner changes for a company — share additions, transfers, and removals, each with a registry-recorded effective date.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from", "required": false, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to", "required": false, "description": "End date (YYYY-MM-DD)" }, { "schema": { "minimum": 1, "maximum": 1000, "default": 500, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum events to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/timeline": { "get": { "operationId": "getCompanyTimeline", "summary": "Company event timeline", "tags": [ "Ownership" ], "description": "Unified chronology of registry-recorded events for a company: officer changes, shareholder changes, status transitions, insolvency/liquidation milestones, pledge activity. Sorted newest-first.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from", "required": false, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to", "required": false, "description": "End date (YYYY-MM-DD)" }, { "schema": { "minimum": 1, "maximum": 1000, "default": 500, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum events to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/ownership-cycles": { "get": { "operationId": "detectOwnershipCycles", "summary": "Detect circular ownership", "tags": [ "Ownership" ], "description": "Walk the ownership graph from this company up to `depth` levels and flag any cycles (A owns B owns C owns A). Circular ownership is a common AML red flag and a UBO-identification blocker.", "parameters": [ { "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "integer" }, "in": "query", "name": "depth", "required": false, "description": "Maximum cycle detection depth" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/risk": { "get": { "operationId": "getCompanyRisk", "summary": "Company risk score", "tags": [ "Risk" ], "description": "Multi-factor risk assessment combining financial stress, sanctions exposure (direct + ownership chain), insolvency/liquidation signals, and registry-status anomalies. Returns a score 0–100 with factor-level breakdowns.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/screening": { "get": { "operationId": "screenCompany", "summary": "Sanctions screening", "tags": [ "Risk" ], "description": "Screen the company and its officers, shareholders, and UBOs against all configured sanctions lists (EU, UN, OFAC, UK HMT). Returns matches with list name, score, and match reasons.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/aml-report": { "get": { "operationId": "generateAmlReport", "summary": "AML due-diligence report", "tags": [ "Risk" ], "description": "Full anti-money-laundering dossier — risk score, sanctions screen of the entity + its network, financial stress indicators, ownership tree, and adverse-media surface. Rate-limited to 5/min and billed against credits. Paid tier only.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/screening/batch": { "post": { "operationId": "batchScreenEntities", "summary": "Batch sanctions screening", "tags": [ "Risk" ], "description": "Screen up to 500 names and/or regcodes in one request. Server-side concurrency is capped. Rate-limited to 5/min and billed against credits. Paid tier only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "minItems": 1, "maxItems": 50, "description": "Entity names or registration codes", "type": "array", "items": { "minLength": 1, "maxLength": 200, "type": "string" } }, "full": { "default": false, "description": "Include full AML report per entity", "type": "boolean" }, "threshold": { "minimum": 0, "maximum": 1, "description": "Minimum sanctions match score (0-1)", "type": "number" }, "concurrency": { "minimum": 1, "maximum": 5, "default": 3, "description": "Parallel processing limit", "type": "integer" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/sanctions/search": { "get": { "operationId": "searchSanctions", "summary": "Search sanctions database", "tags": [ "Sanctions" ], "description": "Full-text search across ingested sanctions lists (EU consolidated, UN, OFAC SDN/NonSDN, UK HMT). Filter by `source` to narrow to a single list. Results include entity type, list name, program, and attribution dates.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Search query" }, { "schema": { "enum": [ "EU", "UN", "OFAC", "UK", "LV" ], "type": "string" }, "in": "query", "name": "source", "required": false, "description": "Sanctions list source" }, { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum results to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/sanctions/screen-person": { "get": { "operationId": "screenPerson", "summary": "Screen a person", "tags": [ "Sanctions" ], "description": "Fuzzy-match a single person against every configured sanctions list. Supply an optional date of birth to tighten the match. Returns candidates ranked by match score with the source list and program.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "name", "required": true, "description": "Person name to screen" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "dob", "required": false, "description": "Date of birth (YYYY-MM-DD)" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/sanctions/stats": { "get": { "operationId": "getSanctionsStats", "summary": "Sanctions database stats", "tags": [ "Sanctions" ], "description": "Counts per list, entity-type breakdowns, and last-ingested timestamps for the sanctions dataset. Cached for one hour.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/sanctions/{id}": { "get": { "operationId": "getSanctionById", "summary": "Get sanction entry", "tags": [ "Sanctions" ], "description": "Fetch a single sanction entry by its internal numeric ID, including the full list attribution, program, aliases, birth/identity markers, and source timestamps.", "parameters": [ { "schema": { "minimum": 1, "type": "integer" }, "in": "path", "name": "id", "required": true, "description": "Sanction entry ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/stats": { "get": { "operationId": "getLandingStats", "summary": "Landing page headline stats", "tags": [ "System" ], "description": "Lightweight overall counts (companies, persons, VID entries, sanctions records) used to populate the public landing page. Cached for one hour.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/stats": { "get": { "operationId": "getRegistryStats", "summary": "Registry-wide statistics", "tags": [ "Analytics" ], "description": "Aggregate counts of active/inactive companies, entity types, flags, and recent registration activity across the whole registry. Cached for one hour.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sectors": { "get": { "operationId": "getSectorBreakdown", "summary": "Company counts by sector", "tags": [ "Analytics" ], "description": "Distribution of active companies across top-level sectors (coarser than NACE — uses the registry's own sector classification).", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum sectors to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/regions": { "get": { "operationId": "getRegionBreakdown", "summary": "Company counts by region", "tags": [ "Analytics" ], "description": "Distribution of active companies across Latvian administrative regions. Pass `showAll=true` to include regions with zero or near-zero counts.", "parameters": [ { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "showAll", "required": false, "description": "Include regions with zero companies" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/trends": { "get": { "operationId": "getRegistrationTrends", "summary": "Registration trends over time", "tags": [ "Analytics" ], "description": "Time series of new company registrations (and closures, if `type=closures`). Pick yearly or monthly granularity and optionally narrow by region.", "parameters": [ { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Entity type filter" }, { "schema": { "minimum": 1900, "maximum": 2100, "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "Start year" }, { "schema": { "minimum": 1900, "maximum": 2100, "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "End year" }, { "schema": { "enum": [ "yearly", "monthly" ], "default": "yearly", "type": "string" }, "in": "query", "name": "granularity", "required": false, "description": "Time granularity" }, { "schema": { "maxLength": 50, "type": "string" }, "in": "query", "name": "region", "required": false, "description": "Filter by region" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/feed/{type}": { "get": { "operationId": "getActivityFeed", "summary": "Recent activity feed", "tags": [ "Analytics" ], "description": "Stream of registry events (`registrations`, `closures`, `insolvencies`, `liquidations`, `sanctions`, `pledges`). Anonymous callers see a shorter window and lower limit; paid tier unlocks full range.", "parameters": [ { "schema": { "minimum": 1, "maximum": 365, "default": 30, "type": "integer" }, "in": "query", "name": "days", "required": false, "description": "Number of days to look back" }, { "schema": { "minimum": 1, "maximum": 500, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum events to return" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip (for pagination)" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "region", "required": false, "description": "Filter by region" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "enum": [ "new", "closed", "insolvent", "sanctioned" ], "type": "string" }, "in": "path", "name": "type", "required": true, "description": "Feed event type" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/prediction": { "get": { "operationId": "getFailureProbability", "summary": "Business failure probability", "tags": [ "Analytics" ], "description": "Model-driven probability that a company will cease operations within the next 12 months, with top contributing factors. Paid tier only.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/nace-sectors": { "get": { "operationId": "getNaceSectorBreakdown", "summary": "Company counts by NACE section", "tags": [ "Analytics" ], "description": "Distribution of active companies across NACE Rev.2 top-level sections (A–U). Cached for one hour.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/persons/search": { "get": { "operationId": "searchPersons", "summary": "Search persons by name", "tags": [ "Persons" ], "description": "Fuzzy search over natural persons known to the registry (officers, shareholders, beneficial owners). Returns candidates with attribution to the companies they're linked to.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Person name to search" }, { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum results to return" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/persons/{id}": { "get": { "operationId": "getPersonProfile", "summary": "Person profile", "tags": [ "Persons" ], "description": "Full profile for a person: all companies they're affiliated with (officer, shareholder, or UBO), role history, and identity markers. Accepts numeric IDs, masked IDs, or a URL-safe name. Anonymous callers receive a redacted view.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Person ID (integer), masked personal ID (DDMMYY-*****), or name" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/persons/{id}/vdaa-enrichment": { "get": { "operationId": "getPersonVdaaEnrichment", "summary": "VDAA person enrichment", "tags": [ "Persons" ], "description": "On-demand lookup against VDAA's NaturalPerson endpoint for additional identity and affiliation data. Call is billed per request and rate-limited by our upstream quota. Paid tier only.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Person ID (integer), masked personal ID (DDMMYY-*****), or name" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/vid": { "get": { "operationId": "getCompanyVid", "summary": "VID tax authority profile", "tags": [ "VID & Network" ], "description": "Data sourced from VID (Valsts ieņēmumu dienests) — tax debt indicator, VAT registration status, and related tax-authority signals. Returned alongside the requested regcode for easy splicing.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/network": { "get": { "operationId": "getCompanyNetwork", "summary": "Company relationship network", "tags": [ "VID & Network" ], "description": "Graph of entities related to a company — shared officers, shareholders, UBOs, and addresses. Filter `rel` limits the returned relationship types. Free tier receives a reduced graph; paid sees the full structure.", "parameters": [ { "schema": { "pattern": "^(officials|shareholders|ubos|reorganizations)(,(officials|shareholders|ubos|reorganizations))*$", "type": "string" }, "in": "query", "name": "rel", "required": false, "description": "Relationship type filter (comma-separated)" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/connections": { "get": { "operationId": "findEntityConnections", "summary": "Connections between entities", "tags": [ "VID & Network" ], "description": "Find the shortest relationship path between two entities (companies or persons) within `depth` degrees. Useful for KYC link analysis and adverse-network discovery. Paid tier only.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "entity1", "required": true, "description": "First entity (regcode or name)" }, { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "entity2", "required": true, "description": "Second entity (regcode or name)" }, { "schema": { "enum": [ "company", "person" ], "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Entity type (auto-detected if omitted)" }, { "schema": { "minimum": 1, "maximum": 10, "default": 5, "type": "integer" }, "in": "query", "name": "depth", "required": false, "description": "Maximum connection depth" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/credit-limit": { "get": { "operationId": "getCreditLimit", "summary": "Computed credit limit", "tags": [ "VID & Network" ], "description": "Suggested trade credit exposure for a company, derived from its financial scale, sector norms, and stress signals. Not a regulated rating — a scoring output for internal decisioning.", "parameters": [ { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/nace/{code}": { "get": { "operationId": "getNaceCode", "summary": "NACE code detail", "tags": [ "NACE" ], "description": "Look up a NACE Rev.2 code and return its descriptions (English + Latvian), direct children in the hierarchy, and full breadcrumb to the top-level section. Cached for 24 hours.", "parameters": [ { "schema": { "pattern": "^[A-Z]$|^\\d{2}$|^\\d{2}\\.\\d{1,2}$", "type": "string" }, "in": "path", "name": "code", "required": true, "description": "NACE code (section letter, division, group, or class)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/nace/{code}/financials": { "get": { "operationId": "getNaceFinancials", "summary": "NACE financial aggregates", "tags": [ "NACE" ], "description": "Aggregate revenue, profit, employee counts, and company totals for all active companies classified under a NACE code. Used to build sector benchmarks and league tables. Cached for one hour.", "parameters": [ { "schema": { "pattern": "^[A-Z]$|^\\d{2}$|^\\d{2}\\.\\d{1,2}$", "type": "string" }, "in": "path", "name": "code", "required": true, "description": "NACE code (section letter, division, group, or class)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/nace/{code}/companies": { "get": { "operationId": "listNaceCompanies", "summary": "Companies under a NACE code", "tags": [ "NACE" ], "description": "Paginated list of companies classified under the given NACE code. Response includes the code's descriptions alongside the company page for easy rendering. Cached for one hour.", "parameters": [ { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" }, { "schema": { "pattern": "^[A-Z]$|^\\d{2}$|^\\d{2}\\.\\d{1,2}$", "type": "string" }, "in": "path", "name": "code", "required": true, "description": "NACE code (section letter, division, group, or class)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/report/{type}": { "get": { "operationId": "generateCompanyReport", "summary": "Generate a company PDF report", "tags": [ "Reports" ], "description": "Render a PDF report for a company (`company`, `aml`, `financial`, or `risk`). Locale controls the report language (`en` default; `lv` also available). Billed against credits — refunded if generation fails. Rate-limited to 10/min. Paid tier only.", "parameters": [ { "schema": { "default": "en", "anyOf": [ { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "lv" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Report language" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "company" ] }, { "type": "string", "enum": [ "aml" ] }, { "type": "string", "enum": [ "financial" ] }, { "type": "string", "enum": [ "risk" ] } ] }, "in": "path", "name": "type", "required": true, "description": "Report type" } ], "responses": { "200": { "description": "Generated PDF report", "content": { "application/pdf": { "schema": { "description": "Binary payload", "type": "string" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/seo/regcodes": { "get": { "operationId": "listRegcodesForSitemap", "summary": "List all regcodes", "tags": [ "System" ], "description": "Paginated catalog of every company registration code known to the registry — used by the web site's sitemap generator. Public, no authentication required. Default page size is 50000.", "parameters": [ { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "Zero-based page index" }, { "schema": { "minimum": 1, "maximum": 50000, "default": 50000, "type": "integer" }, "in": "query", "name": "pageSize", "required": false, "description": "Page size (max 50000)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "regcodes", "entries" ], "properties": { "regcodes": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "type": "object", "required": [ "regcode", "lastmod" ], "properties": { "regcode": { "type": "string" }, "lastmod": { "description": "ISO 8601 timestamp of the last narrative content change for this company, or null when no narrative row exists yet.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/seo/person-ids": { "get": { "operationId": "listPersonIdsForSitemap", "summary": "List all person IDs", "tags": [ "System" ], "description": "Paginated catalog of every numeric person ID known to the registry — used by the web site's sitemap generator for person profile pages. Public, no authentication required.", "parameters": [ { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "Zero-based page index" }, { "schema": { "minimum": 1, "maximum": 50000, "default": 50000, "type": "integer" }, "in": "query", "name": "pageSize", "required": false, "description": "Page size (max 50000)" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "personIds" ], "properties": { "personIds": { "type": "array", "items": { "type": "integer" } } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/chat": { "post": { "operationId": "chatQuery", "summary": "Ask a question (quick mode)", "tags": [ "Chat" ], "description": "Ask a natural-language question about Latvian business registry data. An LLM generates SQL, validates it for safety, and executes it against the database. Returns structured results with the generated SQL, an explanation, column names, and rows (max 500). Costs 1 credit per query. Rate limit: 10 requests per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "question" ], "properties": { "question": { "minLength": 5, "maxLength": 1000, "type": "string" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "anyOf": [ { "type": "object", "required": [ "status", "question", "sql", "explanation", "columns", "rows", "rowCount", "truncated", "retried", "executionTimeMs" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "question": { "type": "string" }, "sql": { "type": "string" }, "explanation": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "rowCount": { "type": "number" }, "truncated": { "type": "boolean" }, "retried": { "type": "boolean" }, "executionTimeMs": { "type": "number" } } }, { "type": "object", "required": [ "status", "question", "refusalReason", "executionTimeMs" ], "properties": { "status": { "type": "string", "enum": [ "refused" ] }, "question": { "type": "string" }, "refusalReason": { "type": "string" }, "executionTimeMs": { "type": "number" } } } ] }, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/chat/agent": { "post": { "operationId": "chatAgent", "summary": "Ask a question (agent mode)", "tags": [ "Chat" ], "description": "Ask a complex natural-language question using the RAG agent. The agent can execute multiple queries, call services, and synthesize answers across data sources. Costs 3 credits per run (refunded on clarification turns and service failures). Supports SSE streaming via `stream: true` in the request body or `Accept: text/event-stream` header. SSE events: `step` (tool execution), `answer` (partial text), `chart` (rendered chart spec), `done` (final result), `error` (service failure, credits refunded). Rate limit: 5 requests per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "question" ], "properties": { "question": { "minLength": 5, "maxLength": 1000, "type": "string" }, "session_id": { "format": "uuid", "type": "string" }, "stream": { "description": "Set to true to receive the response as an SSE stream. Alternative: send Accept: text/event-stream header.", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "anyOf": [ { "type": "object", "required": [ "status", "question", "answer", "steps", "sessionId", "partial", "executionTimeMs" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "question": { "type": "string" }, "answer": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "required": [ "tool", "arguments", "resultSummary", "durationMs" ], "properties": { "tool": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": {} }, "resultSummary": { "type": "string" }, "durationMs": { "type": "number" }, "error": { "type": "string" } } } }, "sessionId": { "type": "string" }, "partial": { "type": "boolean" }, "executionTimeMs": { "type": "number" }, "clarification": { "type": "boolean" }, "followUpSuggestions": { "type": "array", "items": { "type": "string" } }, "chart": { "type": "object", "required": [ "id", "mark", "actionTitle", "sourceLabel", "data", "encoding", "meta" ], "properties": { "id": { "type": "string" }, "mark": { "anyOf": [ { "type": "string", "enum": [ "line" ] }, { "type": "string", "enum": [ "bar_vertical" ] }, { "type": "string", "enum": [ "bar_horizontal" ] }, { "type": "string", "enum": [ "bar_stacked" ] }, { "type": "string", "enum": [ "scatter" ] } ] }, "actionTitle": { "type": "string" }, "sourceLabel": { "type": "string" }, "yUnit": { "type": "string" }, "stacked100": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "encoding": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "object", "required": [ "field", "type", "label" ], "properties": { "field": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" } } }, "y": { "type": "object", "required": [ "field", "type", "label" ], "properties": { "field": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" } } }, "series": { "type": "object", "required": [ "field", "label" ], "properties": { "field": { "type": "string" }, "label": { "type": "string" } } } } }, "meta": { "type": "object", "required": [ "nRows", "queriedAt" ], "properties": { "nRows": { "type": "number" }, "queriedAt": { "type": "string" } } } } } } }, { "type": "object", "required": [ "status", "question", "refusalReason", "executionTimeMs" ], "properties": { "status": { "type": "string", "enum": [ "refused" ] }, "question": { "type": "string" }, "refusalReason": { "type": "string" }, "executionTimeMs": { "type": "number" } } }, { "type": "object", "required": [ "status", "question", "error", "steps", "executionTimeMs" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "question": { "type": "string" }, "error": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "required": [ "tool", "arguments", "resultSummary", "durationMs" ], "properties": { "tool": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": {} }, "resultSummary": { "type": "string" }, "durationMs": { "type": "number" }, "error": { "type": "string" } } } }, "executionTimeMs": { "type": "number" } } } ] }, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/analytics/chat/agent/sessions": { "get": { "operationId": "listChatSessions", "summary": "List chat sessions", "tags": [ "Chat" ], "description": "List the authenticated user's agent chat sessions, ordered by most recently updated. Paginated with limit and offset query parameters.", "parameters": [ { "schema": { "type": "string", "default": "10" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "default": "0" }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/chat/agent/session/{id}": { "get": { "operationId": "getChatSession", "summary": "Get session history", "tags": [ "Chat" ], "description": "Get the conversation history for an agent session. Returns user and assistant turns with clarification flags, chart specs, and follow-up suggestions. Consumers can read expired sessions (read-only) but cannot continue them.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sessionId", "summary", "updatedAt", "turns" ], "properties": { "sessionId": { "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "turns": { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "clarification": { "type": "boolean" }, "clarificationReply": { "type": "boolean" }, "followUpSuggestions": { "type": "array", "items": { "type": "string" } }, "chart": { "type": "object", "required": [ "id", "mark", "actionTitle", "sourceLabel", "data", "encoding", "meta" ], "properties": { "id": { "type": "string" }, "mark": { "anyOf": [ { "type": "string", "enum": [ "line" ] }, { "type": "string", "enum": [ "bar_vertical" ] }, { "type": "string", "enum": [ "bar_horizontal" ] }, { "type": "string", "enum": [ "bar_stacked" ] }, { "type": "string", "enum": [ "scatter" ] } ] }, "actionTitle": { "type": "string" }, "sourceLabel": { "type": "string" }, "yUnit": { "type": "string" }, "stacked100": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "encoding": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "object", "required": [ "field", "type", "label" ], "properties": { "field": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" } } }, "y": { "type": "object", "required": [ "field", "type", "label" ], "properties": { "field": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" } } }, "series": { "type": "object", "required": [ "field", "label" ], "properties": { "field": { "type": "string" }, "label": { "type": "string" } } } } }, "meta": { "type": "object", "required": [ "nRows", "queriedAt" ], "properties": { "nRows": { "type": "number" }, "queriedAt": { "type": "string" } } } } } } } } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } } }, "servers": [ { "url": "https://api.izluks.lv", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "System", "description": "Health checks and system status" }, { "name": "Companies", "description": "Company search, lookup, and comparison" }, { "name": "Financials", "description": "Financial history, ratios, benchmarks, and rankings" }, { "name": "Ownership", "description": "Ownership structure, chains, and history" }, { "name": "Risk", "description": "Risk assessment, screening, and AML reports" }, { "name": "Sanctions", "description": "Sanctions database search and person screening" }, { "name": "Analytics", "description": "Registry statistics, trends, and activity feeds" }, { "name": "Persons", "description": "Person search and profile lookup" }, { "name": "VID & Network", "description": "Tax data, company networks, and connections" }, { "name": "NACE", "description": "NACE industry classification and browsing" }, { "name": "Documents", "description": "Annual reports and public document access" }, { "name": "Pledges", "description": "Commercial pledge records and lookup" }, { "name": "Reports", "description": "PDF report generation and download" } ] }