{ "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", "contact": { "name": "Izluks Support", "email": "atbalsts@izluks.lv", "url": "https://izluks.lv" }, "license": { "name": "Proprietary", "url": "https://izluks.lv/terms" }, "termsOfService": "https://izluks.lv/terms", "x-logo": { "url": "https://izluks.lv/izluks-logo.png", "altText": "Izluks" } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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. Pagination is limited to a 10,000-row window: `(page − 1) × limit + limit` must not exceed 10,000 (deeper OFFSET walks are rejected with 400); `totalPages` in the response stays factual and may exceed the reachable window on broad queries — narrow the filters or use the CSV export for bulk access.", "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, "maximum": 10000, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "Page number ((page − 1) × limit + limit must be ≤ 10,000)" }, { "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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. Rate-limited to 30 requests per minute per caller.", "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); values below 0.2 are clamped to 0.2" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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}/history": { "get": { "operationId": "getCompanyHistory", "summary": "Company ownership & control history", "tags": [ "Companies" ], "description": "Retrieves and normalizes a company's full legal-entity history from the registry — past and present shareholders, officers/representatives, beneficial owners (with control chain), capital structure, and a corporate timeline (name/address/legal-form changes, reorganizations, liquidations, suspensions, securing measures, activity prohibitions, NACE history). Live fetch, credit-gated (5 credits); refunded if retrieval fails. PII is masked.", "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": {} } } } } } } }, "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}/history/report": { "get": { "operationId": "exportCompanyHistoryReport", "summary": "Export the company history as a PDF (free)", "tags": [ "Companies" ], "description": "Renders the already-generated company history (shareholders, officers/representatives, beneficial owners, capital, procurations, decisive influence, and corporate timeline) as a branded PDF. Free — does not charge credits — but requires the history to have been generated first (via GET /companies/{regcode}/history). Returns 409 HISTORY_NOT_GENERATED when no cached history exists. Locale controls the report language (`en` default; `lv` also available).", "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" } ], "responses": { "200": { "description": "Company history PDF export", "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": {} } } } } } } }, "409": { "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": {} } } } } } } }, "502": { "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/api/v1/companies/{regcode}/financials/export.xlsx": { "get": { "operationId": "exportCompanyFinancialsXlsx", "summary": "Export financial statements as XLSX", "tags": [ "Financials" ], "description": "Downloads the company's filed annual statements as a workbook — a summary sheet plus one sheet each for the profit-and-loss account, the balance sheet and the cash-flow statement, with the filed years as columns running oldest to newest. Each year carries its own currency (pre-2014 filings are in LVL and are never converted) and its consolidated-or-standalone scope, and a statement no year filed is left out rather than printed empty. Free of charge but requires a signed-in session; a free account exports the three most recent filed years, a subscription exports the full history. Labels follow `locale` (`lv` default; `en` also available). Rate-limited to 10 per minute.", "parameters": [ { "schema": { "default": "lv", "anyOf": [ { "type": "string", "enum": [ "lv" ] }, { "type": "string", "enum": [ "en" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Label language for the exported file" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Financial statements as an XLSX workbook", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "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": {} } } } } } } }, "401": { "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/companies/{regcode}/financials/export.csv": { "get": { "operationId": "exportCompanyFinancialsCsv", "summary": "Export financial statements as CSV", "tags": [ "Financials" ], "description": "The same filed statements as the XLSX export, delivered as one CSV with the profit-and-loss account, balance sheet and cash-flow statement stacked as labelled sections sharing the same year columns, oldest to newest. Values are raw numbers with no locale formatting, and a missing figure is an empty cell rather than a zero. The body is UTF-8 and begins with a byte-order mark (U+FEFF) so Excel on Windows reads Latvian labels correctly — strip it before parsing if your reader does not. Free of charge but requires a signed-in session; a free account exports the three most recent filed years, a subscription exports the full history. Labels follow `locale` (`lv` default; `en` also available). Rate-limited to 10 per minute.", "parameters": [ { "schema": { "default": "lv", "anyOf": [ { "type": "string", "enum": [ "lv" ] }, { "type": "string", "enum": [ "en" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Label language for the exported file" }, { "schema": { "pattern": "^[T]?\\d{8,11}$", "type": "string" }, "in": "path", "name": "regcode", "required": true, "description": "Company registration code" } ], "responses": { "200": { "description": "Financial statements as CSV", "content": { "text/csv": { "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": {} } } } } } } }, "401": { "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/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}/shareholders": { "get": { "operationId": "getCompanyShareholders", "summary": "Paginated direct shareholders", "tags": [ "Ownership" ], "description": "Direct shareholders for a company, paginated. The unpaginated profile endpoint embeds only the first page; use this endpoint to walk the full list. Set `kind=sia` for private LLC shareholders, `kind=as` for joint-stock shareholders, `kind=partnership` for KS/PS partnership members. sia/as are sorted by share count descending; partnership members are sorted general partners first, then by contribution value — KS/PS 'shares' are not ownership fractions, so no percentages apply.", "parameters": [ { "schema": { "enum": [ "sia", "as", "partnership" ], "type": "string" }, "in": "query", "name": "kind", "required": true, "description": "Shareholder kind: 'sia' (private LLC), 'as' (joint-stock), or 'partnership' (KS/PS members — contribution values, not ownership percentages)." }, { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Page size (max 100)." }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Row offset for pagination." }, { "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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. Available to any authenticated user with sufficient credits.", "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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 AML screening", "tags": [ "Risk" ], "description": "Resolve up to 50 names and/or Latvian registration codes against the registry and return a full AML assessment for each — sanctions screening, red flags, risk rating, and financial health. A name is resolved only when it identifies exactly one company; anything ambiguous or uncertain is returned with `regcode: null` and is instead screened by NAME against the sanctions lists, giving status `REVIEW` when its name matches a listing and `UNRESOLVED` when it matches nothing. A row is therefore never reported as assessed against a company that merely resembles the input. Server-side concurrency is capped. Rate-limited to 5/min and billed against credits. Available to any authenticated user with sufficient credits. To screen a list of counterparties against the sanctions lists alone — up to 500, free, recorded as evidence, and with the per-hit detail — use `POST /api/v1/screening/runs/batch` instead.", "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": "Raise-only confidence bar for resolving a name to a company (0-1). The default floor is 0.9 and a lower value has no effect; it cannot widen the search. Not a sanctions match score.", "type": "number" }, "concurrency": { "minimum": 1, "maximum": 5, "default": 3, "description": "Parallel processing limit", "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/api/v1/sanctions/search": { "get": { "operationId": "searchSanctions", "summary": "Search sanctions database", "tags": [ "Sanctions" ], "description": "Search across all ingested sanctions lists (EU, UN, OFAC SDN + Consolidated, UK, LV, CA, AU, CH). Supply a name query (`q`, trigram over names + aliases) and/or advanced filters: `sources` (comma-separated), `entityType`, `subjectKind`, `program`, `programGroup`, `measure`, `nationality`, `citizenship`, `country`, `dobFrom`/`dobTo` (birth-year range), `dobDate` (exact date of birth), `documentNumber`, `docType`, `docCountry`, `docIssuedFrom`/`docIssuedTo`, `docValidFrom`/`docValidTo`, `vesselFlag`, `listedFrom`/`listedTo`, `position`, `placeOfBirth`, `address`, `remarks`. Option lists for the dropdown filters come from `GET /api/v1/sanctions/search-filters`. `exact=true` matches the name literally rather than fuzzily; `qScope=all` widens `q` to document numbers, addresses and the designation narrative; `status=delisted|any` reaches subjects that were removed from a list, labelling each row with `status` and `delisted_on` (a historical record, never a current designation — see the parameter for the filters it cannot answer). At least one of a query or a filter is required (none of `exact`, `qScope` and `status` is a filter). Results are paginated (`page`, `limit` ≤ 100) and returned in a paginated envelope (`meta.total`, `meta.page`). Every result is a possible match requiring verification, never a determination.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false, "description": "Name query (trigram over names + aliases). Optional when at least one filter is given." }, { "schema": { "enum": [ "EU", "UN", "OFAC", "OFAC-CONS", "UK", "LV", "CA", "AU", "CH" ], "type": "string" }, "in": "query", "name": "source", "required": false, "description": "Single sanctions list source (back-compat; use `sources` for multi-select)" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "sources", "required": false, "description": "Comma-separated sources to include (e.g. `EU,OFAC,UK`)" }, { "schema": { "enum": [ "individual", "entity" ], "type": "string" }, "in": "query", "name": "entityType", "required": false, "description": "Restrict to individuals or entities" }, { "schema": { "enum": [ "individual", "entity", "vessel", "aircraft" ], "type": "string" }, "in": "query", "name": "subjectKind", "required": false, "description": "Restrict to a subject kind. A fourth axis beside `entityType`, not a replacement — vessels and aircraft are also `entityType=entity`" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "program", "required": false, "description": "Programme / regime substring (case-insensitive); an exact `programs` value when `exact=true`" }, { "schema": { "enum": [ "russia", "belarus", "ukraine-territorial", "iran", "dprk", "syria", "terrorism", "myanmar", "venezuela", "libya", "human-rights", "cyber", "chemical-weapons", "non-proliferation", "narcotics", "other-regimes" ], "type": "string" }, "in": "query", "name": "programGroup", "required": false, "description": "Curated programme group — one regime across every list's own naming (e.g. `russia` covers OFAC `RUSSIA-EO14024`, EU `UKR`, UK's regulation title)" }, { "schema": { "enum": [ "asset-freeze", "arms-embargo", "targeted-arms-embargo", "chartering-of-ships", "closure-of-representative-offices", "crew-servicing-of-ships-and-aircraft", "deflag", "prevention-of-business-arrangements", "port-entry", "travel-ban", "prevention-of-chartering-of-ships", "prevention-of-chartering-of-ships-and-aircraft", "technical-assistance-related-to-aircraft", "trust-services", "director-disqualification", "maritime-restriction" ], "type": "string" }, "in": "query", "name": "measure", "required": false, "description": "What the designation does (`asset-freeze`, `travel-ban`, `arms-embargo`, ...). Only the UK and Australian lists publish per-measure indicators, so this filter reaches ~19% of subjects by construction" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "nationality", "required": false, "description": "Nationality. A bare ISO 3166-1 alpha-2 code matches the normalized codes exactly; anything else is a case-insensitive substring over the published strings" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "citizenship", "required": false, "description": "Citizenship, same code-or-substring behaviour as `nationality` (OFAC-only data)" }, { "schema": { "pattern": "^[A-Za-z]{2}$", "type": "string" }, "in": "query", "name": "country", "required": false, "description": "Country (ISO 3166-1 alpha-2) — the subject's own country or any of its addresses'" }, { "schema": { "minimum": 1000, "maximum": 3000, "type": "integer" }, "in": "query", "name": "dobFrom", "required": false, "description": "Earliest birth year (inclusive)" }, { "schema": { "minimum": 1000, "maximum": 3000, "type": "integer" }, "in": "query", "name": "dobTo", "required": false, "description": "Latest birth year (inclusive)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "dobDate", "required": false, "description": "Exact date of birth (`YYYY-MM-DD`). Subjects whose listing gives only a year still match on that year, so a full-date query never drops them" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "documentNumber", "required": false, "description": "Identity / passport / document-number prefix" }, { "schema": { "enum": [ "passport", "national-id", "tax-id", "registration-number", "license", "imo", "mmsi", "vessel-registration", "aircraft-id", "travel-document", "driver-license", "birth-certificate", "residence-permit", "financial-id", "crypto-address", "other-document" ], "type": "string" }, "in": "query", "name": "docType", "required": false, "description": "Curated document kind, over ~211 as-published `id_type` labels" }, { "schema": { "pattern": "^[A-Za-z]{2}$", "type": "string" }, "in": "query", "name": "docCountry", "required": false, "description": "Document issuing country (ISO 3166-1 alpha-2)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "docIssuedFrom", "required": false, "description": "Document issued on or after (`YYYY-MM-DD`)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "docIssuedTo", "required": false, "description": "Document issued on or before (`YYYY-MM-DD`)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "docValidFrom", "required": false, "description": "Document expires on or after (`YYYY-MM-DD`)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "docValidTo", "required": false, "description": "Document expires on or before (`YYYY-MM-DD`)" }, { "schema": { "pattern": "^[A-Za-z]{2}$", "type": "string" }, "in": "query", "name": "vesselFlag", "required": false, "description": "Vessel flag state (ISO 3166-1 alpha-2)" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "listedFrom", "required": false, "description": "Listed on or after (`YYYY-MM-DD`). OFAC publishes no per-entry listing date" }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "listedTo", "required": false, "description": "Listed on or before (`YYYY-MM-DD`)" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "position", "required": false, "description": "Position / office substring (case-insensitive)" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "placeOfBirth", "required": false, "description": "Place-of-birth substring (case-insensitive)" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "address", "required": false, "description": "Address text match (word similarity + containment)" }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "remarks", "required": false, "description": "Free-text remarks substring (case-insensitive)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "exact", "required": false, "description": "Match the name query literally instead of fuzzily, and read `program` as an exact value. A modifier, not a filter — it does not on its own satisfy the query-or-filter requirement" }, { "schema": { "enum": [ "name", "all" ], "default": "name", "type": "string" }, "in": "query", "name": "qScope", "required": false, "description": "How wide `q` reads. `name` (the default) searches names and aliases; `all` additionally searches document numbers, addresses and the designation narrative (remarks + statement of reasons). A modifier, not a filter — it does not on its own satisfy the query-or-filter requirement, and it is inert below three characters. For anonymous callers the document and address halves cover organisations and vessels only (DP-1)" }, { "schema": { "enum": [ "active", "delisted", "any" ], "default": "active", "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Which subjects to search. `active` (the default) reaches only currently listed subjects; `delisted` reaches only subjects an authority has since removed from its list; `any` reaches both and labels every row with `status` and `delisted_on`. A delisted row is a historical record that the designation once existed and has ended — it is never a current designation, and no screening path reads it. A modifier, not a filter: it does not on its own satisfy the query-or-filter requirement. The historical record is minimised to name, type, programmes and the two dates, so only `source`/`sources`, `entityType`, `subjectKind`, `program` and `listedFrom`/`listedTo` can be answered over it. Combining any other filter — `measure` and `programGroup` included, as both are computed over the live table only — drops the delisted half rather than erroring: `any` returns today's live-only results and `delisted` returns an empty page." }, { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "1-based page number" }, { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Page size (max 100)" }, { "schema": { "enum": [ "relevance", "name", "listed_on" ], "type": "string" }, "in": "query", "name": "sort", "required": false, "description": "Sort key; `relevance` falls back to name when there is no query" }, { "schema": { "type": "boolean" }, "in": "query", "name": "desc", "required": false, "description": "Descending order (applies to name / listed_on sorts)" }, { "schema": { "enum": [ "json", "csv" ], "type": "string" }, "in": "query", "name": "format", "required": false, "description": "Response format" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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, "maximum": 2147483647, "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/sanctions/subject/{slug}": { "get": { "operationId": "getSanctionSubject", "summary": "Get sanctions subject detail", "tags": [ "Sanctions" ], "description": "Fetch a single sanctions subject for the public subject page by its durable `{source}-{source_id}` slug (e.g. `EU-201`, `OFAC-CONS-123`) or a numeric sanction id. Returns the official-list mirror — including vessel particulars (`vessels`), published contact points (`contacts`), gender, citizenships, restrictive measures, legal basis and the authority's statement of reasons — plus Latvian registry cross-links (`registryLinks`), the per-subject add/amend/remove/re-key history, and the source's latest list-version date. DP-1: for individuals, identity/document numbers, residential addresses and contact points are returned only to authenticated callers; entities are a full mirror. The response carries `canonicalSlug` so numeric-id URLs can redirect to the stable slug. A `source_id` the issuing authority has retired resolves to a minimised historical record with `delisted: true` (no identifiers, addresses, vessels or contacts, for any caller); if it was retired by a re-key rather than a delisting, `supersededBy` names the identifier that now carries the same — still listed — party.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 256, "type": "string" }, "in": "path", "name": "slug", "required": true, "description": "Subject slug — the durable `{source}-{source_id}` composite (e.g. `EU-201`, `OFAC-CONS-123`), or a numeric sanction id which resolves to the same subject (the response carries `canonicalSlug` for a redirect)." } ], "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/sanctions/changes": { "get": { "operationId": "getSanctionsChanges", "summary": "Sanctions list change feed", "tags": [ "Sanctions" ], "description": "The public change-event stream across every list (`sanctions_history`, Phase 0.3), newest first. Filter by `source`, `eventType` (added / removed / amended / rekeyed), and `window` (7 / 30 / 90 / 365 days or `all`). Paginated (`page`, `limit` ≤ 50). Backfilled anchor events are excluded, so every row is a real observed change. `rekeyed` means the issuing authority retired one `source_id` and still carries the same party under another — the party remains listed, so it is never a delisting. Each item carries the subject's public name, entity type, and programmes plus a `subjectSlug` linking to the subject page (removed and re-keyed subjects resolve to their historical record). Anonymous access; cached one hour.", "parameters": [ { "schema": { "enum": [ "EU", "UN", "OFAC", "OFAC-CONS", "UK", "LV", "CA", "AU", "CH" ], "type": "string" }, "in": "query", "name": "source", "required": false, "description": "Restrict to a single sanctions list source" }, { "schema": { "enum": [ "added", "removed", "amended", "rekeyed" ], "type": "string" }, "in": "query", "name": "eventType", "required": false, "description": "Restrict to one change type. `rekeyed` is an upstream re-key or de-duplication — the issuing authority retired one `source_id` and still carries the same party under another, so it is never a delisting." }, { "schema": { "enum": [ "7", "30", "90", "365", "all" ], "default": "30", "type": "string" }, "in": "query", "name": "window", "required": false, "description": "Window on the event date, in days back from today (`all` = whole history)" }, { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "1-based page number" }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Page size (max 50)" } ], "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/list-versions": { "get": { "operationId": "getSanctionsListVersions", "summary": "Sanctions list publication dates", "tags": [ "Sanctions" ], "description": "Per-source freshness: the authority's own list publication date (DP-3) and our last fetch, from `sanctions_list_versions`, in canonical source order. Backs the freshness ribbon on the sanctions surfaces. Anonymous access; cached 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/documents": { "get": { "operationId": "getSanctionsDocuments", "summary": "Sanctions documents feed", "tags": [ "Sanctions" ], "description": "The public feed of official sanctions legal acts and notices (`sanctions_documents`, Phase 1.3b), newest first — title, publication date, source, the publisher's own summary, and outbound link only (no content mirroring). Populated during the daily refresh from **two** upstream feeds: the UK OFSI Atom feed and OFAC via the US Federal Register per-agency feed. Documents are therefore ingested for **OFAC and UK only**; filtering to any other source returns an empty page rather than an error. Filter by `source` and `window` (7 / 30 / 90 / 365 days or `all`). Paginated (`page`, `limit` ≤ 50). Anonymous access; cached one hour.", "parameters": [ { "schema": { "enum": [ "EU", "UN", "OFAC", "OFAC-CONS", "UK", "LV", "CA", "AU", "CH" ], "type": "string" }, "in": "query", "name": "source", "required": false, "description": "Restrict to a single sanctions list source. Documents are currently ingested for OFAC and UK only; other sources return an empty page." }, { "schema": { "enum": [ "7", "30", "90", "365", "all" ], "default": "30", "type": "string" }, "in": "query", "name": "window", "required": false, "description": "Window on the document date, in days back from today (`all` = every document)" }, { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "1-based page number" }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Page size (max 50)" } ], "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-filters": { "get": { "operationId": "getSanctionsSearchFilters", "summary": "Advanced-search option lists", "tags": [ "Sanctions" ], "description": "The selectable values behind the advanced sanctions search, with the number of subjects carrying each — ten facets: `subject_kind`, `program_group`, `program`, `nationality`, `citizenship`, `country`, `doc_kind`, `doc_country`, `vessel_flag`, `measure`. Values are ordered most-common first, and the country-shaped facets (`nationality`, `citizenship`, `country`, `doc_country`, `vessel_flag`) carry ISO 3166-1 alpha-2 codes for the caller to label. Read from a materialized view rebuilt by the daily refresh, so `refreshedAt` is that run, not request time. Aggregates only — no subject data. Anonymous access; cached 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/screening/run": { "post": { "operationId": "runScreeningCheck", "summary": "Screen a subject and record the check", "tags": [ "Sanctions" ], "description": "Screens one subject against every ingested sanctions list and stores the check as evidence: what was screened, when, against which list versions, with which matching threshold and engine version. A `company` check also screens the company's officials, shareholders, and UBOs. Every result is a possible match requiring verification, never a determination. Requires a signed-in session; free of charge. Rate-limited to 20 checks per minute, and to 200 recorded checks or 10000 counterparties screened per rolling 24 hours — the allowance frees up as earlier checks age past 24 hours.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subjectType" ], "properties": { "subjectType": { "enum": [ "person", "entity", "company" ], "description": "What is being screened: `person` (a natural person by name), `entity` (an organisation by name — typically non-Latvian), or `company` (a Latvian registration code, which also screens its officials, shareholders, and UBOs)", "type": "string" }, "name": { "minLength": 1, "maxLength": 200, "description": "Subject name. Required for `person` and `entity`.", "type": "string" }, "dob": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth (YYYY-MM-DD), persons only. Raises the score of a hit whose listed date of birth matches.", "type": "string" }, "country": { "maxLength": 100, "description": "Country of the subject, recorded with the check as evidence. It does not narrow the result set. Not needed for `company` — a Latvian registration code states the jurisdiction, and the recorded check names it.", "type": "string" }, "regcode": { "minLength": 1, "maxLength": 20, "description": "Latvian registration code. Required for `company`.", "type": "string" }, "reference": { "maxLength": 120, "description": "Your own case or client reference, stored with the check so it can be filed against your records.", "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": {} } } } } } } }, "401": { "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/screening/batch/parse": { "post": { "operationId": "parseScreeningBatchFile", "summary": "Read a counterparty list from a spreadsheet", "tags": [ "Sanctions" ], "description": "Reads an uploaded `.csv` or `.xlsx` counterparty list and returns its columns, its rows, and a proposed assignment of each column (name, registration code, date of birth, country, reference). Handles the formats spreadsheet software actually exports — semicolon separators, a UTF-8 byte-order mark, windows-1257 encoding, and files with no header row. Nothing is screened, stored, or written to disk at this stage: confirm the column assignment and post the rows to `/api/v1/screening/runs/batch`. Send the file as `multipart/form-data` under any field name. Whether the first row is a header is inferred; send a `hasHeader` field of `true` or `false` BEFORE the file part to state it outright. Limited to 500 rows and 2 MB, and to workbooks that stay under 32 MB when opened. Requires a signed-in session; free of charge. Rate-limited to 10 uploads per minute.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The uploaded file" } }, "required": [ "file" ] } } } }, "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": {} } } } } } } }, "401": { "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": {} } } } } } } }, "413": { "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/runs/batch": { "post": { "operationId": "runBatchScreeningCheck", "summary": "Screen a counterparty list and record the check", "tags": [ "Sanctions" ], "description": "Screens up to 500 counterparties against every ingested sanctions list and stores the whole list as ONE recorded check — one act covering the batch, with the same list-version, threshold, and engine snapshot as a single check, and the same per-match decisions. A row carrying a Latvian registration code is screened by the company's registered name; unlike a single company check it does not also screen that company's officials, shareholders, and beneficial owners, so run a single check on a row when you need that depth. Every result is a possible match requiring verification, never a determination. Requires a signed-in session; free of charge. Rate-limited to 5 batches per minute, and to 200 recorded checks or 10000 counterparties screened per rolling 24 hours — the allowance frees up as earlier checks age past 24 hours.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "rows" ], "properties": { "fileName": { "minLength": 1, "maxLength": 200, "description": "Name of the uploaded list. Becomes the act's subject line.", "type": "string" }, "reference": { "maxLength": 120, "description": "Your own case or client reference for the batch as a whole.", "type": "string" }, "rows": { "minItems": 1, "maxItems": 500, "description": "The counterparties to screen. Each row needs a name or a Latvian registration code — a code resolves to the registered name.", "type": "array", "items": { "type": "object", "required": [ "line" ], "properties": { "line": { "minimum": 1, "description": "The row's 1-based position in your file, so results map back to it.", "type": "integer" }, "name": { "maxLength": 200, "type": "string" }, "regcode": { "maxLength": 20, "type": "string" }, "dob": { "maxLength": 20, "description": "Date of birth as `1970-04-02`, `02.04.1970`, or `02/04/1970`.", "type": "string" }, "country": { "maxLength": 100, "type": "string" }, "reference": { "maxLength": 120, "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": {} } } } } } } }, "401": { "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": {} } } } } } } }, "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/screening/runs": { "get": { "operationId": "listScreeningRuns", "summary": "List your screening checks", "tags": [ "Sanctions" ], "description": "Your screening register, newest first — every check you have run, with its act number, subject, your own reference, hit count, and current disposition. This is the compliance file a supervisor asks to see. Paginated (`page`, `limit` ≤ 50). Requires a signed-in session and returns only your own records.", "parameters": [ { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "1-based page number" }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Page size (max 50)" } ], "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": {} } } } } } } }, "401": { "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/runs/{id}": { "get": { "operationId": "getScreeningRun", "summary": "Get one screening check", "tags": [ "Sanctions" ], "description": "The full record of a single check: the subject as submitted, every possible match with its score, the per-source list versions in force at the time, the matching threshold and engine version, and the complete append-only decision trail. Also carries `priorVerdicts` — your own standing decisions from earlier checks on the same subject and the same listed party, one per match you have not yet decided here. Those are recalled, not applied: they are not decisions on this check until you record them (`POST .../adjudications/carry`), and they never appear on the certificate. Requires a signed-in session; another user's check is reported as not found.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Screening run id (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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/runs/{id}/adjudications": { "post": { "operationId": "adjudicateScreeningRun", "summary": "Record a decision on a check", "tags": [ "Sanctions" ], "description": "Records a decision: `confirmed` / `dismissed` on one possible match (`scope: hit` with its `hitKey`), or `cleared` / `escalated` / `blocked` for the counterparty as a whole (`scope: run`). Append-only — deciding again adds a record and the newest one applies, so the full history of who decided what, when, and why is preserved. Returns the refreshed check. Rate-limited to 60 decisions per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "status" ], "properties": { "scope": { "enum": [ "hit", "run" ], "description": "`hit` decides one possible match; `run` records the counterparty-level conclusion for the whole check", "type": "string" }, "hitKey": { "minLength": 1, "maxLength": 32, "description": "Which possible match is being decided. Required when `scope` is `hit`.", "type": "string" }, "status": { "enum": [ "confirmed", "dismissed", "cleared", "escalated", "blocked" ], "description": "`confirmed` / `dismissed` for a hit; `cleared` / `escalated` / `blocked` for the run", "type": "string" }, "reason": { "maxLength": 2000, "description": "Why the decision was taken — the part an inspector reads", "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Screening run id (UUID)" } ], "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": {} } } } } } } }, "401": { "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/runs/{id}/adjudications/carry": { "post": { "operationId": "carryScreeningVerdicts", "summary": "Carry your standing decisions onto this check", "tags": [ "Sanctions" ], "description": "Records, as decisions on THIS check, every verdict you already hold on the same subject and the same listed party from an earlier check — the `priorVerdicts` the check reports. Each is written with today's date and names the check it was carried from, so the record never reads as a fresh judgment. Matches you have already decided here are skipped, so pressing twice records nothing twice. Append-only like any other decision: deciding again afterwards supersedes it and the whole trail survives. The check-level conclusion is never carried. Returns the refreshed check, with `meta.carried` giving how many decisions this call actually wrote. Requires a signed-in session; another user's check is reported as not found.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Screening run id (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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/runs/{id}/certificate": { "get": { "operationId": "getScreeningCertificate", "summary": "Issue the screening certificate as a PDF", "tags": [ "Sanctions" ], "description": "Renders a stored check as a dated, list-versioned certificate — the artifact handed to an auditor or a supervisor. It states who screened whom, at what exact time, against which list versions, with which threshold and engine, every possible match with its recorded decision, and the disclaimer that the document is an automated comparison rather than a determination. Nothing is re-screened: the certificate reproduces the stored record, so reissuing it years later still reports the lists as they stood on the day of the check. Free of charge; requires a signed-in session; another user's check is reported as not found. Locale controls the language (`en` default; `lv` also available). Rate-limited to 10 per minute.", "parameters": [ { "schema": { "default": "en", "anyOf": [ { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "lv" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Report language" }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Screening run id (UUID)" } ], "responses": { "200": { "description": "Screening certificate PDF", "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": {} } } } } } } }, "401": { "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/runs/{id}/export.csv": { "get": { "operationId": "exportScreeningRunCsv", "summary": "Export a screening check as CSV", "tags": [ "Sanctions" ], "description": "Downloads a stored check as a spreadsheet: one line per possible match, repeating each counterparty's own columns, plus one line for every counterparty that matched nothing — the export accounts for every subject screened, not just the interesting ones. A list check exports its uploaded roster; a single check exports its subject plus every further name the check reached (a company check fans out to its officials, shareholders and beneficial owners), with `screened_role` naming which, so a match against a shareholder is never read as a match against the company. The act number, timestamp, threshold, engine, and per-source list versions ride in a header block, so a saved file is still self-describing a year later. Nothing is re-screened. Free of charge; requires a signed-in session; another user's check is reported as not found. Rate-limited to 10 per minute.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Screening run id (UUID)" } ], "responses": { "200": { "description": "Screening results as CSV", "content": { "text/csv": { "schema": { "description": "Binary payload", "type": "string" } } } }, "401": { "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/portfolios": { "get": { "operationId": "listScreeningPortfolios", "summary": "List your saved counterparty lists", "tags": [ "Sanctions" ], "description": "Every portfolio you keep, newest first, with how many counterparties it holds, how they currently stand, and when the list was last screened. Requires a signed-in session and returns only your own lists. You can keep 20 portfolios holding 500 counterparties in total.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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": {} } } } } } } } } }, "post": { "operationId": "createScreeningPortfolio", "summary": "Save a counterparty list", "tags": [ "Sanctions" ], "description": "Creates a portfolio: the counterparties you intend to keep screening. Give `entries` to build one directly, or `sourceRunId` to save an existing list check's counterparties along with the results it already produced — that path screens nothing again. A registration code resolves to the registered name, and the same counterparty submitted twice is stored once. Creating a list does not screen it; post to `/screen` when you want that. Requires a signed-in session; free of charge. You can keep 20 portfolios holding 500 counterparties in total. Rate-limited to 20 per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 120, "description": "What you call this list. It becomes the subject line of every act it produces.", "type": "string" }, "entries": { "minItems": 1, "maxItems": 500, "description": "The counterparties to keep on the list. Each needs a name or a Latvian registration code; the same counterparty submitted twice is stored once.", "type": "array", "items": { "type": "object", "properties": { "name": { "maxLength": 200, "description": "Counterparty name. Required unless a registration code is given.", "type": "string" }, "regcode": { "maxLength": 20, "description": "Latvian registration code. Resolves to the registered name, which is what gets screened and stored.", "type": "string" }, "dob": { "maxLength": 20, "description": "Date of birth as `1970-04-02`, `02.04.1970`, or `02/04/1970`.", "type": "string" }, "country": { "maxLength": 100, "type": "string" }, "reference": { "maxLength": 120, "description": "Your own case or client reference for this counterparty.", "type": "string" } } } }, "sourceRunId": { "minLength": 1, "maxLength": 64, "description": "Save an existing list check's counterparties as a portfolio, carrying their results across. Nothing is screened again. Give this or `entries`, not both.", "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": {} } } } } } } }, "401": { "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": {} } } } } } } }, "409": { "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/portfolios/{id}": { "get": { "operationId": "getScreeningPortfolio", "summary": "Get one counterparty list", "tags": [ "Sanctions" ], "description": "The full list: every counterparty on it, how each currently stands, when it was last screened, and which recorded check produced that standing. A counterparty that has never been screened has no standing at all — that is not the same as one that came back clear. Requires a signed-in session; another user's list is reported as not found.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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": {} } } } } } } } } }, "patch": { "operationId": "renameScreeningPortfolio", "summary": "Rename a counterparty list", "tags": [ "Sanctions" ], "description": "Changes what the list is called. Acts already recorded keep the name they were run under — a record says what it said on the day. Rate-limited to 20 per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 120, "description": "The list's new name.", "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" } ], "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": {} } } } } } } }, "401": { "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": {} } } } } } } }, "409": { "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": {} } } } } } } } } }, "delete": { "operationId": "deleteScreeningPortfolio", "summary": "Delete a counterparty list", "tags": [ "Sanctions" ], "description": "Removes the list and everything on it. The checks it produced stay in your register: they are dated records of screening that really happened, and deleting the list does not undo them. Rate-limited to 20 per minute.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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/portfolios/{id}/entries": { "post": { "operationId": "addScreeningPortfolioEntries", "summary": "Add counterparties to a list", "tags": [ "Sanctions" ], "description": "Adds counterparties to an existing list. Anything already on it is reported as skipped rather than duplicated. A newly added counterparty has no standing until you screen the list again — it is not reported clear on the strength of a check it was never part of. You can keep 20 portfolios holding 500 counterparties in total. Rate-limited to 20 per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "minItems": 1, "maxItems": 500, "description": "The counterparties to keep on the list. Each needs a name or a Latvian registration code; the same counterparty submitted twice is stored once.", "type": "array", "items": { "type": "object", "properties": { "name": { "maxLength": 200, "description": "Counterparty name. Required unless a registration code is given.", "type": "string" }, "regcode": { "maxLength": 20, "description": "Latvian registration code. Resolves to the registered name, which is what gets screened and stored.", "type": "string" }, "dob": { "maxLength": 20, "description": "Date of birth as `1970-04-02`, `02.04.1970`, or `02/04/1970`.", "type": "string" }, "country": { "maxLength": 100, "type": "string" }, "reference": { "maxLength": 120, "description": "Your own case or client reference for this counterparty.", "type": "string" } } } } } } } } }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" } ], "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": {} } } } } } } }, "401": { "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/screening/portfolios/{id}/entries/{entryId}": { "delete": { "operationId": "removeScreeningPortfolioEntry", "summary": "Remove a counterparty from a list", "tags": [ "Sanctions" ], "description": "Takes one counterparty off the list. Checks that already covered it stay in your register unchanged. Rate-limited to 20 per minute.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "entryId", "required": true, "description": "Entry id (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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/portfolios/{id}/screen": { "post": { "operationId": "screenScreeningPortfolio", "summary": "Screen a counterparty list and record the check", "tags": [ "Sanctions" ], "description": "Screens every counterparty on the list against every ingested sanctions list and records the whole thing as ONE check — the same kind of act an uploaded list produces, with the same list-version, threshold and engine snapshot, the same certificate, and the same per-match decisions. Each counterparty's standing on the list is updated from the result. A row carrying a Latvian registration code is screened by the company's registered name; it does not also screen that company's officials, shareholders and beneficial owners, so run a single check when you need that depth. Every result is a possible match requiring verification, never a determination. Requires a signed-in session; free of charge. Rate-limited to 5 per minute, and to 200 recorded checks or 10000 counterparties screened per rolling 24 hours.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Portfolio id (UUID)" } ], "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": {} } } } } } } }, "401": { "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/screening/alerts": { "get": { "operationId": "listScreeningAlerts", "summary": "List your monitoring alerts", "tags": [ "Sanctions" ], "description": "Alerts the daily monitoring pass produced for your portfolios, newest first, with when the last pass ran. Each day the pass screens every counterparty you keep against just that day's sanctions-list changes: a possible new match becomes a `new_hit` alert, and the removal of a subject you were alerted about becomes a `delisted` notice. An alert is a possible match requiring verification, never a determination — screen the list to record a check that settles it. An alert changes no counterparty's standing on the list. Requires a signed-in session and returns only your own alerts.\n\nEach alert carries a `resolution`, derived at read time from your own checks and decisions and never stored: `open` (no check made since the alert was raised), `undecided` (a check names the subject and the match is still to assess — `runId`, `rowKey` and `hitKey` address it), or `settled` (the match carries a decision, or the check names no such subject). Alerts are never deleted or marked read: the log is monitoring evidence, and the check is what settles one.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "query", "name": "portfolioId", "required": false, "description": "Only alerts for this portfolio. Someone else's portfolio id returns nothing." }, { "schema": { "minimum": 1, "maximum": 100, "default": 30, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Newest-first page size." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "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/registry-state": { "get": { "operationId": "getRegistryState", "summary": "State-of-the-registry kiosk aggregate", "tags": [ "Analytics" ], "description": "Single-round-trip payload for the /analytics landing kiosk: headline totals, 7d/30d/365d registration and closure deltas, risk weather (sanctions, insolvencies, commercial pledges), and top-5 sectors by 30d net growth. Served from the mv_registry_state materialized view per the analytics cost contract. 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). Served from the mv_sector_breakdown materialized view per the analytics cost contract; refreshed nightly. Cached for one hour.", "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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. Served from the mv_region_breakdown materialized view per the analytics cost contract; refreshed nightly. Cached for one hour.", "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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. Served from the mv_registration_trends materialized view per the analytics cost contract; refreshed nightly. Cached for one hour.", "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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, "maximum": 20000, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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/analytics/risks/freshness": { "get": { "operationId": "getRisksFreshness", "summary": "Risks materialized-view freshness", "tags": [ "Analytics" ], "description": "Last-refresh timestamp, row count, and refresh duration for the materialized views that back the registry-wide Risks page. Anonymous access. Items include the spine `mv_company_risk_signals` and any `mv_risk_*` MVs as they ship in subsequent phases.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "mvName", "refreshedAt", "rowCount", "durationMs" ], "properties": { "mvName": { "description": "Materialized-view name", "type": "string" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful refresh (ISO-8601)", "type": "string" }, "rowCount": { "description": "Row count after the most recent refresh", "type": "integer" }, "durationMs": { "description": "Refresh duration in milliseconds", "type": "integer" } } } } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/overview": { "get": { "operationId": "getRisksOverview", "summary": "Risks page hero KPIs", "tags": [ "Analytics" ], "description": "Registry-wide distress index, high-severity company count, 30-day new-signals total, and 30-day declining-firms total, sourced from `mv_risk_hero_kpis` (refreshed daily). Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "distressIndex", "highSeverityCount", "newSignals30d", "decliningFirms30d", "refreshedAt" ], "properties": { "distressIndex": { "minimum": 0, "maximum": 100, "description": "Registry-wide distress index (0–100), AVG of per-company distress_pts.", "type": "number" }, "highSeverityCount": { "minimum": 0, "description": "Active companies in severity tier 'crit' or 'high'.", "type": "integer" }, "newSignals30d": { "description": "New signal events in the last 30 days, sourced from `mv_risk_stream_daily_series`. Null only when the hero MV has no row.", "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "decliningFirms30d": { "description": "Distinct firms that picked up a new signal in the last 30 days. Null only when the hero MV has no row.", "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/streams": { "get": { "operationId": "getRisksStreams", "summary": "Risks page six-stream cards", "tags": [ "Analytics" ], "description": "Per-stream summary for the six risk-type cards: active count, 7-day and 30-day event windows with delta-percent, top NACE sections, and a 30-day sparkline. Sourced from `mv_risk_stream_cards` and `mv_risk_stream_daily_series` (refreshed daily). Anonymous access. Streams are returned in a fixed order.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "streams", "refreshedAt" ], "properties": { "streams": { "minItems": 6, "maxItems": 6, "description": "Always six entries in fixed order: insolvency, sanctions, vid_status, overdue_filing, pledges, disqualifications.", "type": "array", "items": { "type": "object", "required": [ "stream", "activeCount", "events7d", "events30d", "deltaPct7d", "deltaPct30d", "topSectors", "sparkline" ], "properties": { "stream": { "description": "Stream identifier — fixed set of six risk streams.", "anyOf": [ { "type": "string", "enum": [ "insolvency" ] }, { "type": "string", "enum": [ "sanctions" ] }, { "type": "string", "enum": [ "vid_status" ] }, { "type": "string", "enum": [ "overdue_filing" ] }, { "type": "string", "enum": [ "pledges" ] }, { "type": "string", "enum": [ "disqualifications" ] } ] }, "activeCount": { "minimum": 0, "description": "Companies currently flagged for this stream (spine state).", "type": "integer" }, "events7d": { "minimum": 0, "description": "Events in the last 7 days.", "type": "integer" }, "events30d": { "minimum": 0, "description": "Events in the last 30 days.", "type": "integer" }, "deltaPct7d": { "description": "% change vs the prior 7-day window. Null when prior window had zero events.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deltaPct30d": { "description": "% change vs the prior 30-day window. Null when prior window had zero events.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "topSectors": { "description": "Top NACE sections by active count for this stream (up to 3).", "type": "array", "items": { "type": "object", "required": [ "sectionCode", "count" ], "properties": { "sectionCode": { "description": "NACE section letter (A–U).", "type": "string" }, "count": { "minimum": 0, "description": "Active companies in this section.", "type": "integer" } } } }, "sparkline": { "description": "Daily event counts for the last 30 days, oldest first, zero-filled.", "type": "array", "items": { "type": "object", "required": [ "date", "count" ], "properties": { "date": { "format": "date", "description": "ISO date (YYYY-MM-DD).", "type": "string" }, "count": { "minimum": 0, "description": "Events on this day.", "type": "integer" } } } } } } }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/heatmap": { "get": { "operationId": "getRisksHeatmap", "summary": "Risks page sectoral heatmap", "tags": [ "Analytics" ], "description": "NACE section × stream heatmap with rate-per-1000 active companies and a quintile-within-stream intensity bucket (0–5). Sourced from `mv_risk_sector_heatmap` (refreshed daily). Companies with no NACE classification are excluded from cells and surfaced via `unclassifiedActiveShare` for the methodology footnote. Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sections", "streams", "cells", "unclassifiedActiveShare", "refreshedAt" ], "properties": { "sections": { "description": "All NACE sections with at least one active company, sorted by sectionCode.", "type": "array", "items": { "type": "object", "required": [ "sectionCode", "labelEn", "labelLv", "activeCount" ], "properties": { "sectionCode": { "description": "NACE section letter (A–U).", "type": "string" }, "labelEn": { "description": "Section description (English).", "type": "string" }, "labelLv": { "description": "Section description (Latvian).", "type": "string" }, "activeCount": { "minimum": 0, "description": "Active companies in this section (rate-per-1000 denominator).", "type": "integer" } } } }, "streams": { "minItems": 6, "maxItems": 6, "description": "Stream order — same fixed six-stream order as `/streams`: insolvency, sanctions, vid_status, overdue_filing, pledges, disqualifications.", "type": "array", "items": { "description": "Stream identifier — fixed set of six risk streams.", "anyOf": [ { "type": "string", "enum": [ "insolvency" ] }, { "type": "string", "enum": [ "sanctions" ] }, { "type": "string", "enum": [ "vid_status" ] }, { "type": "string", "enum": [ "overdue_filing" ] }, { "type": "string", "enum": [ "pledges" ] }, { "type": "string", "enum": [ "disqualifications" ] } ] } }, "cells": { "description": "Long-form cells, sections.length × 6 entries.", "type": "array", "items": { "type": "object", "required": [ "sectionCode", "stream", "count", "ratePer1000", "intensity" ], "properties": { "sectionCode": { "description": "NACE section letter (A–U).", "type": "string" }, "stream": { "description": "Stream identifier — fixed set of six risk streams.", "anyOf": [ { "type": "string", "enum": [ "insolvency" ] }, { "type": "string", "enum": [ "sanctions" ] }, { "type": "string", "enum": [ "vid_status" ] }, { "type": "string", "enum": [ "overdue_filing" ] }, { "type": "string", "enum": [ "pledges" ] }, { "type": "string", "enum": [ "disqualifications" ] } ] }, "count": { "minimum": 0, "description": "Companies in this section currently flagged for this stream.", "type": "integer" }, "ratePer1000": { "minimum": 0, "description": "Per 1 000 active companies in this section.", "type": "number" }, "intensity": { "minimum": 0, "maximum": 5, "description": "0 when count = 0; otherwise NTILE(5) within the stream by ratePer1000.", "type": "integer" } } } }, "unclassifiedActiveShare": { "minimum": 0, "maximum": 1, "description": "Share of active companies with no NACE classification (0..1). Footnote-only.", "type": "number" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/ladder": { "get": { "operationId": "getRisksLadder", "summary": "Risks page severity ladder", "tags": [ "Analytics" ], "description": "Four-row severity ladder (Critical / High / Medium / Low) with active-company counts and 30-day month-over-month deltas. Sourced from `mv_risk_severity_ladder` (refreshed daily) with prior-period counts from `risk_severity_tier_history`. The first ~30 daily runs return `momDeltaPct = null` until history accrues. Anonymous access. Tiers are returned in fixed display order.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "tiers", "flaggedTotal", "refreshedAt" ], "properties": { "tiers": { "minItems": 4, "maxItems": 4, "description": "Always four entries in fixed display order: crit, high, med, low.", "type": "array", "items": { "type": "object", "required": [ "tier", "count", "momDeltaCount", "momDeltaPct", "refreshedAt" ], "properties": { "tier": { "description": "Severity tier identifier — fixed four-element set in display order: crit, high, med, low.", "anyOf": [ { "type": "string", "enum": [ "crit" ] }, { "type": "string", "enum": [ "high" ] }, { "type": "string", "enum": [ "med" ] }, { "type": "string", "enum": [ "low" ] } ] }, "count": { "minimum": 0, "description": "Active companies currently in this tier.", "type": "integer" }, "momDeltaCount": { "description": "Today's count − count from the 30-day-prior snapshot. Null when no prior snapshot exists.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "momDeltaPct": { "description": "% change vs the 30-day-prior snapshot. Null when prior count was 0 or absent (the first ~30 daily runs).", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } } }, "flaggedTotal": { "minimum": 0, "description": "Sum of `count` across all four tiers — companies with ≥1 signal.", "type": "integer" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/insolvency": { "get": { "operationId": "getRisksInsolvencyDrilldown", "summary": "Insolvency risk drilldown (counts + recent list)", "tags": [ "Analytics" ], "description": "Powers the /analytics/risks/insolvency page. Returns distinct-company counts of new insolvency proceedings over 7d/30d/365d windows, plus the 50 most recently insolvent companies (one row per company, latest proceeding wins). Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "counts", "recent", "refreshedAt" ], "properties": { "counts": { "type": "object", "required": [ "week", "month", "year" ], "properties": { "week": { "minimum": 0, "description": "Distinct companies with a new proceeding in the past 7 days.", "type": "integer" }, "month": { "minimum": 0, "description": "Distinct companies with a new proceeding in the past 30 days.", "type": "integer" }, "year": { "minimum": 0, "description": "Distinct companies with a new proceeding in the past 365 days.", "type": "integer" } } }, "recent": { "maxItems": 50, "description": "Most recently insolvent companies, deduped (latest proceeding per company).", "type": "array", "items": { "type": "object", "required": [ "regcode", "name", "proceedingStartedOn", "proceedingType", "proceedingForm", "courtName" ], "properties": { "regcode": { "description": "Company registration code.", "type": "string" }, "name": { "description": "Company name.", "type": "string" }, "proceedingStartedOn": { "format": "date", "description": "Date the proceeding was opened (ISO-8601 calendar date).", "type": "string" }, "proceedingType": { "description": "Raw type code (e.g. 'NATIONAL'). Backend stays English; frontend handles i18n.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proceedingForm": { "description": "Raw form code: 'INSOLVENCY' | 'LEGAL_PROTECTION' | 'OUT_OF_COURT_LEGAL_PROTECTION'.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "courtName": { "description": "Court name (Latvian, as stored upstream).", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "refreshedAt": { "format": "date-time", "description": "Server clock at query time (no MV behind this endpoint).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/vid": { "get": { "operationId": "getRisksVidDrilldown", "summary": "VID suspension risk drilldown (counts + recent list)", "tags": [ "Analytics" ], "description": "Powers the /analytics/risks/vid page. Returns distinct-company counts of newly suspended companies over 7d/30d/365d windows (keyed on `suspended_from`), plus the 50 most recently suspended companies (one row per company, latest suspension wins). Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "counts", "recent", "refreshedAt" ], "properties": { "counts": { "type": "object", "required": [ "week", "month", "year" ], "properties": { "week": { "minimum": 0, "description": "Distinct companies newly suspended by VID in the past 7 days.", "type": "integer" }, "month": { "minimum": 0, "description": "Distinct companies newly suspended by VID in the past 30 days.", "type": "integer" }, "year": { "minimum": 0, "description": "Distinct companies newly suspended by VID in the past 365 days.", "type": "integer" } } }, "recent": { "maxItems": 50, "description": "Most recently suspended companies, deduped (latest suspension per company).", "type": "array", "items": { "type": "object", "required": [ "regcode", "name", "suspendedFrom", "suspendedUntil" ], "properties": { "regcode": { "description": "Company registration code.", "type": "string" }, "name": { "description": "Company name.", "type": "string" }, "suspendedFrom": { "format": "date", "description": "Date the business-activity suspension took effect (ISO-8601 calendar date).", "type": "string" }, "suspendedUntil": { "description": "Date the suspension is scheduled to lift, or null for an indefinite suspension.", "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] } } } }, "refreshedAt": { "format": "date-time", "description": "Server clock at query time (no MV behind this endpoint).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/risks/pledges": { "get": { "operationId": "getRisksPledgesDrilldown", "summary": "Commercial-pledge risk drilldown (counts + recent list)", "tags": [ "Analytics" ], "description": "Powers the /analytics/risks/pledges page. Returns distinct-pledgor counts of newly registered active pledges over 7d/30d/365d windows (keyed on `registered_on`, scoped to is_annulled=FALSE AND removed_on IS NULL to match the landing-card MV), plus an `active` total across all open pledges and the 50 most recently registered pledges (one row per pledgor, latest pledge wins). Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "counts", "recent", "refreshedAt" ], "properties": { "counts": { "type": "object", "required": [ "week", "month", "year", "active" ], "properties": { "week": { "minimum": 0, "description": "Distinct pledgors with a new active pledge registered in the past 7 days.", "type": "integer" }, "month": { "minimum": 0, "description": "Distinct pledgors with a new active pledge registered in the past 30 days.", "type": "integer" }, "year": { "minimum": 0, "description": "Distinct pledgors with a new active pledge registered in the past 365 days.", "type": "integer" }, "active": { "minimum": 0, "description": "Distinct pledgors with at least one currently active pledge (no date filter).", "type": "integer" } } }, "recent": { "maxItems": 50, "description": "Most recently registered active pledges, deduped (latest pledge per pledgor).", "type": "array", "items": { "type": "object", "required": [ "regcode", "name", "registeredOn", "amount", "currency" ], "properties": { "regcode": { "description": "Pledgor company registration code.", "type": "string" }, "name": { "description": "Company name. Falls back to the upstream party name when no `companies` row exists.", "type": "string" }, "registeredOn": { "format": "date", "description": "Date the pledge was registered (ISO-8601 calendar date).", "type": "string" }, "amount": { "description": "Secured amount in the pledge's currency, or null if unspecified.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "description": "ISO-4217 currency code, or null if unspecified.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "refreshedAt": { "format": "date-time", "description": "Server clock at query time (no MV behind this endpoint).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/freshness": { "get": { "operationId": "getSanctionsFreshness", "summary": "Sanctions materialized-view freshness", "tags": [ "Analytics" ], "description": "Last-refresh timestamp, row count, and refresh duration for the materialized views that back the registry-wide Sanctions page. Anonymous access. Items list any `mv_sanctions_*` MVs as they ship in Phases 5.2–5.6.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "mvName", "refreshedAt", "rowCount", "durationMs" ], "properties": { "mvName": { "description": "Materialized-view name", "type": "string" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful refresh (ISO-8601)", "type": "string" }, "rowCount": { "description": "Row count after the most recent refresh", "type": "integer" }, "durationMs": { "description": "Refresh duration in milliseconds", "type": "integer" } } } } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/overview": { "get": { "operationId": "getSanctionsOverview", "summary": "Sanctions page hero KPIs", "tags": [ "Analytics" ], "description": "Registry-wide sanctions hero ribbon: LV-linked subjects (1°), total subjects across all lists, active sources, and subjects newly designated in the last seven days (counted from real `added` list-change events, not a stock difference). Sourced from `mv_sanctions_hero` (refreshed daily). Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "lvLinkedSubjects", "totalSubjects", "activeSources", "newThisWeek", "extensionExposedCompanies", "refreshedAt" ], "properties": { "lvLinkedSubjects": { "minimum": 0, "description": "Distinct LV-linked subjects (1°): unique `legal_entity_regcode` values in `sanctions_flags`.", "type": "integer" }, "totalSubjects": { "minimum": 0, "description": "Distinct subjects across all nine lists, deduped on `(source, source_id)` (the UNIQUE constraint on `sanctions`).", "type": "integer" }, "activeSources": { "minimum": 0, "description": "Sources with at least one row in `sanctions` today. The page anticipates nine; v1 lands data for six (EU/OFAC/OFAC-CONS/UK/UN/LV; CA lands too).", "type": "integer" }, "newThisWeek": { "minimum": 0, "description": "Distinct subjects newly designated across all lists in the last seven days — counted from real (non-backfilled) `added` events in the list-change history, so onboarding a new source is not reported as a week of designations and genuine additions are not netted away by removals.", "type": "integer" }, "extensionExposedCompanies": { "minimum": 0, "description": "Distinct LV companies with computed ownership-rule (extension) exposure — `COUNT(DISTINCT regcode) FROM sanctions_extension_exposure`. Powers the (flag-gated) 5th hero cell; 0 until the daily extension-exposure precompute has run.", "type": "integer" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/exposed": { "get": { "operationId": "getSanctionsExposed", "summary": "Sanctions page top-exposed table", "tags": [ "Analytics" ], "description": "LV companies with ≥1 direct sanctions hit, sorted by latest flag date desc, flag count desc. Sourced from `mv_sanctions_exposed` (refreshed daily). Default page size is 50; hard cap is 200. v1 ships 1°-only — officer/UBO 2° fan-out is deferred. Anonymous access.", "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum rows to return (default 50, capped at 200)." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "rows", "refreshedAt" ], "properties": { "rows": { "description": "LV companies with ≥1 direct sanctions hit, sorted by `latestFlaggedOn DESC NULLS LAST, flagCount DESC, regcode`. Capped at the `limit` query parameter.", "type": "array", "items": { "type": "object", "required": [ "regcode", "legalName", "sectionCode", "sectionLabelEn", "sectionLabelLv", "flagCount", "sources", "firstFlaggedOn", "latestFlaggedOn", "companyStatus" ], "properties": { "regcode": { "description": "LV company registration code (`companies.regcode`).", "type": "string" }, "legalName": { "description": "Company legal name as stored on `companies.name`.", "type": "string" }, "sectionCode": { "description": "NACE section letter (A–U); null for unclassified companies.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sectionLabelEn": { "description": "English NACE section description; null for unclassified companies.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sectionLabelLv": { "description": "Latvian NACE section description; null for unclassified companies.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "flagCount": { "minimum": 1, "description": "Number of `sanctions_flags` rows for this company (one per source-hit).", "type": "integer" }, "sources": { "description": "Distinct sources the company's hits trace to, normalised to the `SANCTION_SOURCES` set (EU/OFAC/UK/UN/CA/AU/CH/LV). Future ingest codes that are not yet mapped surface verbatim — never silently dropped.", "type": "array", "items": { "type": "string" } }, "firstFlaggedOn": { "description": "Earliest `COALESCE(registered_on, entry_date)` for this company (ISO-8601).", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "latestFlaggedOn": { "description": "Most recent `COALESCE(registered_on, entry_date)` for this company (ISO-8601).", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "companyStatus": { "description": "Derived from `companies.closed`: 'active' (NULL or whitespace), 'liquidated' ('L'), 'reorganizing' ('R'), or the raw closed code. Frontend i18n maps these into LV/EN/RU.", "type": "string" } } } }, "refreshedAt": { "format": "date-time", "description": "Earliest `refreshed_at` across the returned rows (ISO-8601). Falls back to the unix epoch when no rows are returned — the freshness route still reports the per-MV refresh timestamp.", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/extension-exposed": { "get": { "operationId": "getSanctionsExtensionExposed", "summary": "Sanctions page 2° (extension-exposed) companies", "tags": [ "Analytics" ], "description": "LV companies owned/controlled by extension (≥50% aggregated ownership) by a designated party — the 2° fan-out behind the analytics extension count. From `sanctions_extension_exposure` (rebuilt daily; tens of rows). Sorted by ownership-hop degree asc, aggregate % desc. Default page size 50, hard cap 200. Computed indicators, never a determination. Anonymous access.", "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum rows to return (default 50, capped at 200)." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "rows", "refreshedAt" ], "properties": { "rows": { "description": "LV companies owned/controlled by extension (≥50% aggregated) by a designated party, sorted by degree asc then aggregate % desc. From `sanctions_extension_exposure` (rebuilt daily; tens of rows). Computed indicators under the ownership-rule, never a determination. Capped at `limit`.", "type": "array", "items": { "type": "object", "required": [ "regcode", "legalName", "maxDegree", "regimes", "maxAggregatePct", "companyStatus" ], "properties": { "regcode": { "description": "LV registration code of the exposed company.", "type": "string" }, "legalName": { "description": "Registered company name (falls back to the regcode).", "type": "string" }, "maxDegree": { "minimum": 1, "maximum": 2, "description": "Ownership-hop degree from a designated party: 1 = directly owned, 2 = two hops. Directly-listed companies (degree 0) are NOT here — they are 1°, in the top-exposed table.", "type": "integer" }, "regimes": { "description": "Regimes under which the company is exposed (EU/UK/OFAC), in that order.", "type": "array", "items": { "type": "string" } }, "maxAggregatePct": { "description": "Highest aggregate designated ownership across the company's regime rows.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "companyStatus": { "description": "Derived from `companies.closed`: 'active', 'liquidated' ('L'), 'reorganizing' ('R'), or the raw code.", "type": "string" } } } }, "refreshedAt": { "format": "date-time", "description": "Earliest `computed_at` across the returned rows (ISO-8601); unix epoch when empty.", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/sources": { "get": { "operationId": "getSanctionsSources", "summary": "Sanctions page source panel", "tags": [ "Analytics" ], "description": "Per-source summary for the nine-card sanctions panel: subject count, LV-linked subjects, last-updated timestamp, and 30-day MoM delta (count + percent). Sourced from `mv_sanctions_sources` (refreshed daily) with prior-period counts from `sanctions_count_history`. The first ~30 daily runs return null `momDeltaCount`/`momDeltaPct` until history accrues. All nine sources have live ingest (AU DFAT + CH SECO since Phase 0.2b). Anonymous access. Sources are returned in a fixed order.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "cards", "refreshedAt" ], "properties": { "cards": { "minItems": 9, "maxItems": 9, "description": "Always nine entries in fixed display order: EU, OFAC, UK, UN, CA, AU, CH, LV, OFAC-CONS. All nine sources have live ingest (AU DFAT + CH SECO since Phase 0.2b) and render visible cards on the analytics page.", "type": "array", "items": { "type": "object", "required": [ "source", "subjectCount", "lvLinkedSubjects", "lastUpdated", "momDeltaCount", "momDeltaPct" ], "properties": { "source": { "description": "Sanctions-list identifier — fixed nine-element set in display order: EU, OFAC, UK, UN, CA, AU, CH, LV, OFAC-CONS.", "anyOf": [ { "type": "string", "enum": [ "EU" ] }, { "type": "string", "enum": [ "OFAC" ] }, { "type": "string", "enum": [ "UK" ] }, { "type": "string", "enum": [ "UN" ] }, { "type": "string", "enum": [ "CA" ] }, { "type": "string", "enum": [ "AU" ] }, { "type": "string", "enum": [ "CH" ] }, { "type": "string", "enum": [ "LV" ] }, { "type": "string", "enum": [ "OFAC-CONS" ] } ] }, "subjectCount": { "minimum": 0, "description": "Total subjects on this source's list (rows on `sanctions`).", "type": "integer" }, "lvLinkedSubjects": { "minimum": 0, "description": "Distinct LV-linked subjects (1°) — `legal_entity_regcode` count in `sanctions_flags`, normalised back to this source.", "type": "integer" }, "lastUpdated": { "description": "Most recent `last_updated` timestamp on `sanctions` for this source (ISO-8601). Null when the source has zero rows.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "momDeltaCount": { "description": "Today's `subjectCount` minus the 30-day-prior snapshot. Null until ≥30 daily snapshots accrue.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "momDeltaPct": { "description": "Percent change vs the 30-day-prior snapshot. Null when the prior snapshot is missing or zero.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "refreshedAt": { "format": "date-time", "description": "Earliest `refreshed_at` across the nine rows (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/sectors": { "get": { "operationId": "getSanctionsSectors", "summary": "Sanctions page sectoral exposure", "tags": [ "Analytics" ], "description": "NACE section × sanctions exposure: distinct LV companies with ≥1 direct hit, the active-firm denominator, and rate-per-1000. Sourced from `mv_sanctions_sectors` (refreshed daily). v1 ships 1°-only (officer/UBO 2° fan-out is deferred). Companies with no NACE classification are excluded from the row set and surfaced via `unclassifiedActiveShare` for the §5.7 methodology footnote. Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sectors", "unclassifiedActiveShare", "refreshedAt" ], "properties": { "sectors": { "description": "All NACE sections with at least one active company, sorted by sectionCode.", "type": "array", "items": { "type": "object", "required": [ "sectionCode", "sectionLabelEn", "sectionLabelLv", "exposedCount", "totalActive", "ratePer1000" ], "properties": { "sectionCode": { "description": "NACE section letter (A–U).", "type": "string" }, "sectionLabelEn": { "description": "Section description (English).", "type": "string" }, "sectionLabelLv": { "description": "Section description (Latvian).", "type": "string" }, "exposedCount": { "minimum": 0, "description": "Distinct LV companies in this section with ≥1 direct sanctions hit (1°). v1 ships only `legal_entity_regcode` matches; officer/UBO 2° fan-out is deferred.", "type": "integer" }, "totalActive": { "minimum": 0, "description": "Active companies in this section (rate-per-1000 denominator).", "type": "integer" }, "ratePer1000": { "minimum": 0, "description": "Per 1 000 active companies in this section.", "type": "number" } } } }, "unclassifiedActiveShare": { "minimum": 0, "maximum": 1, "description": "Share of active companies with no NACE classification (0..1). Footnote-only.", "type": "number" }, "refreshedAt": { "format": "date-time", "description": "Timestamp of the most recent successful MV refresh (ISO-8601).", "type": "string" } } }, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/analytics/sanctions/recent": { "get": { "operationId": "getSanctionsRecent", "summary": "Sanctions page recent-additions feed", "tags": [ "Analytics" ], "description": "Sanction entries from the trailing 7-day window, grouped to one row per `(subjectName, source, flaggedOn::date)`. Sourced from `mv_sanctions_recent` (refreshed daily). v1 ships 1°-only — `lvLinkCount` counts distinct LV-linked legal entities for the `+N LV link` impact note. The feed is empty on most days when no flag rows arrive in the window. Anonymous access.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "entries", "refreshedAt" ], "properties": { "entries": { "description": "Sanction entries from the trailing 7-day window, sorted by `flaggedOn DESC, source, subjectName`. One row per `(subjectName, source, flaggedOn::date)`. Empty when no entries land in the window.", "type": "array", "items": { "type": "object", "required": [ "source", "flaggedOn", "subjectName", "program", "lvLinkCount" ], "properties": { "source": { "description": "Sanctions-list identifier — fixed nine-element set in display order: EU, OFAC, UK, UN, CA, AU, CH, LV, OFAC-CONS.", "anyOf": [ { "type": "string", "enum": [ "EU" ] }, { "type": "string", "enum": [ "OFAC" ] }, { "type": "string", "enum": [ "UK" ] }, { "type": "string", "enum": [ "UN" ] }, { "type": "string", "enum": [ "CA" ] }, { "type": "string", "enum": [ "AU" ] }, { "type": "string", "enum": [ "CH" ] }, { "type": "string", "enum": [ "LV" ] }, { "type": "string", "enum": [ "OFAC-CONS" ] } ] }, "flaggedOn": { "format": "date-time", "description": "Newest of `registered_on` / `entry_date` for this entry within the trailing 7-day window (ISO-8601).", "type": "string" }, "subjectName": { "description": "Sanction subject name as stored on `sanctions_flags.name`.", "type": "string" }, "program": { "description": "Programs the subject is sanctioned under, joined with `; ` when multiple programs share the same source-date group. Null when every underlying flag row has a null program.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lvLinkCount": { "minimum": 0, "description": "Distinct LV-linked legal entities attached to this entry (1°). Frontend surfaces non-zero entries as `+N LV link`.", "type": "integer" } } } }, "refreshedAt": { "format": "date-time", "description": "Earliest `refreshed_at` across the returned rows (ISO-8601). Falls back to the unix epoch when the feed is empty — the freshness route still reports the per-MV refresh timestamp.", "type": "string" } } }, "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": 3, "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Person name to search (minimum 3 characters — shorter queries fall back to an unindexed scan and are rejected)" }, { "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } } } } }, "/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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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}/site-profile": { "post": { "operationId": "generateSiteProfile", "summary": "Generate a Site Profile for a company", "tags": [ "Companies" ], "description": "Deeper read of a company sourced from its own_domain website. Live retrieval, NLI-gated, credit-charged (5), refunded on abstain (domain_unconfirmed, no_pages_fetched, extraction_empty, nli_dropped_all) and on throw. When SITE_PROFILE_PROMO_FREE is on, the charge is skipped entirely (no refund is issued, since none was charged). Rate-limited 5/minute per user. Feature-flagged via COMPANY_SITE_PROFILE_FEATURE_ENABLED.", "parameters": [ { "schema": { "default": "lv", "anyOf": [ { "type": "string", "enum": [ "lv" ] }, { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "ru" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Output language for the generated summary" }, { "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": { "type": "object", "required": [ "summary_md", "sectors", "products", "geography", "scale_signals", "contacts", "content_pool", "abstained", "abstain_reason", "built_at", "served_from", "content_hash" ], "properties": { "summary_md": { "type": "string" }, "sectors": { "type": "array", "items": { "type": "string" } }, "products": { "type": "array", "items": { "type": "string" } }, "geography": { "type": "array", "items": { "type": "string" } }, "scale_signals": { "type": "array", "items": { "type": "string" } }, "contacts": { "type": "object", "required": [ "phones", "emails", "address", "named" ], "properties": { "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "named": { "type": "array", "items": { "type": "object", "required": [ "name", "role", "email", "phone" ], "properties": { "name": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "content_pool": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "text" ], "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" } } } }, "abstained": { "type": "boolean" }, "abstain_reason": { "anyOf": [ { "type": "string", "enum": [ "domain_unconfirmed" ] }, { "type": "string", "enum": [ "no_pages_fetched" ] }, { "type": "string", "enum": [ "extraction_empty" ] }, { "type": "string", "enum": [ "nli_dropped_all" ] }, { "type": "null" } ] }, "built_at": { "type": "string" }, "served_from": { "anyOf": [ { "type": "string", "enum": [ "live" ] }, { "type": "string", "enum": [ "cache" ] } ] }, "content_hash": { "type": "string" }, "age_hours": { "type": "integer" }, "forced": { "type": "boolean", "enum": [ true ] } } }, "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": {} } } } } } } }, "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": {} } } } } } } }, "500": { "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": {} } } } } } } } } }, "get": { "operationId": "getCachedSiteProfile", "summary": "Read a cached Company Site Profile", "tags": [ "Companies" ], "description": "Returns the cached site profile written by a prior paid POST. Free (no credits, no rate limit). Returns 404 SITE_PROFILE_NOT_GENERATED when the cache row is absent, older than COMPANY_SITE_PROFILE_CACHE_TTL_HOURS (default 1440h / 60d), or the inferred own-domain has changed since the row was written. Feature-flagged via COMPANY_SITE_PROFILE_FEATURE_ENABLED.", "parameters": [ { "schema": { "default": "lv", "anyOf": [ { "type": "string", "enum": [ "lv" ] }, { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "ru" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Output language for the generated summary" }, { "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": { "type": "object", "required": [ "summary_md", "sectors", "products", "geography", "scale_signals", "contacts", "content_pool", "abstained", "abstain_reason", "built_at", "served_from", "content_hash" ], "properties": { "summary_md": { "type": "string" }, "sectors": { "type": "array", "items": { "type": "string" } }, "products": { "type": "array", "items": { "type": "string" } }, "geography": { "type": "array", "items": { "type": "string" } }, "scale_signals": { "type": "array", "items": { "type": "string" } }, "contacts": { "type": "object", "required": [ "phones", "emails", "address", "named" ], "properties": { "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "named": { "type": "array", "items": { "type": "object", "required": [ "name", "role", "email", "phone" ], "properties": { "name": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "content_pool": { "type": "array", "items": { "type": "object", "required": [ "url", "title", "text" ], "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" } } } }, "abstained": { "type": "boolean" }, "abstain_reason": { "anyOf": [ { "type": "string", "enum": [ "domain_unconfirmed" ] }, { "type": "string", "enum": [ "no_pages_fetched" ] }, { "type": "string", "enum": [ "extraction_empty" ] }, { "type": "string", "enum": [ "nli_dropped_all" ] }, { "type": "null" } ] }, "built_at": { "type": "string" }, "served_from": { "anyOf": [ { "type": "string", "enum": [ "live" ] }, { "type": "string", "enum": [ "cache" ] } ] }, "content_hash": { "type": "string" }, "age_hours": { "type": "integer" }, "forced": { "type": "boolean", "enum": [ true ] } } }, "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": {} } } } } } } }, "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": {} } } } } } } }, "500": { "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}/site-profile/feedback": { "post": { "operationId": "submitSiteProfileFeedback", "summary": "Rate a Site Profile", "tags": [ "Companies" ], "description": "Submit write-once thumbs-up/down feedback (optional comment, max 2000 chars) for one profile version, identified by (regcode, locale, built_at). Idempotent per (user, profile version) — the first submission is final. Free: no credits, rate-limited 5/minute per user. Feature-flagged via COMPANY_SITE_PROFILE_FEATURE_ENABLED.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "locale", "built_at", "rating" ], "properties": { "locale": { "anyOf": [ { "type": "string", "enum": [ "lv" ] }, { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "ru" ] } ] }, "built_at": { "format": "date-time", "maxLength": 40, "type": "string" }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up" ] }, { "type": "string", "enum": [ "down" ] } ] }, "comment": { "maxLength": 2000, "type": "string" } } } } } }, "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": {} } } } } } } }, "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": {} } } } } } } }, "500": { "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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. Observer 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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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": "OK", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } }, "text/csv": { "schema": { "description": "CSV-encoded rows. First row contains column headers.", "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": {} } } } } } } }, "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/search": { "get": { "operationId": "searchNaceCodes", "summary": "Search NACE codes", "tags": [ "NACE" ], "description": "Autocomplete-style search across NACE Rev.2 codes by Latvian / English description or code prefix. Used by the mobile filter NACE picker. Cached for one hour.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 100, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Search term (description text or code prefix)" }, { "schema": { "enum": [ "lv", "en" ], "default": "lv", "type": "string" }, "in": "query", "name": "lang", "required": false, "description": "Description language to prioritise (lv default)" }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Max results (cap 50)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/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, "maximum": 1000, "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. Available to any authenticated user with sufficient credits.", "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/persons/{id}/report/person": { "get": { "operationId": "generatePersonReport", "summary": "Generate a person PDF report", "tags": [ "Reports" ], "description": "Render a person profile PDF (registry roles + VDAA enrichment: career history, binding authority, commercial pledges, spousal property contracts). Full unmasked personal code is included. Charges 5 credits — refunded on render failure. Paid tier only (Agent or Analyst). Rate-limited to 10/min.", "parameters": [ { "schema": { "default": "en", "anyOf": [ { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "lv" ] } ] }, "in": "query", "name": "locale", "required": false, "description": "Report language" }, { "schema": { "pattern": "^[1-9][0-9]{0,15}$", "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Person ID (positive integer person row id, as returned by /persons/search)" } ], "responses": { "200": { "description": "Generated person profile PDF", "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/persons/{id}/report/person/csv": { "get": { "operationId": "generatePersonReportCsv", "summary": "Generate the CSV companion to the person profile report", "tags": [ "Reports" ], "description": "Flat CSV dump of the person's complete enrichment history — legal-entity involvements (current + historical), commercial pledges (active + history), and spousal property contracts. Uncapped. Charges 5 credits independently of the PDF. Paid tier only.", "parameters": [ { "schema": { "pattern": "^[1-9][0-9]{0,15}$", "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Person ID (positive integer person row id, as returned by /persons/search)" } ], "responses": { "200": { "description": "CSV", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV-encoded enrichment history. First row is the header." } } } }, "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/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. Optional `context: \"watchlist\"` (+ `window`) injects the caller's watchlist and cached watchlist report into the conversation context (used by the watchlist Report tab's analyst panel).", "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" }, "context": { "description": "Inject the caller's watchlist + cached watchlist report as conversation context (used by the watchlist Report tab's analyst panel). Authenticated users only; ignored for anonymous.", "type": "string", "enum": [ "watchlist" ] }, "window": { "description": "Report window whose cached report seeds the context. Default since_last.", "anyOf": [ { "type": "string", "enum": [ "since_last" ] }, { "type": "string", "enum": [ "7" ] }, { "type": "string", "enum": [ "30" ] }, { "type": "string", "enum": [ "90" ] }, { "type": "string", "enum": [ "all" ] } ] } } } } } }, "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" }, "resultMeta": { "type": "object", "additionalProperties": {} } } } }, "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" } } }, "label_col": { "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" }, "resultMeta": { "type": "object", "additionalProperties": {} } } } }, "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" } } }, "label_col": { "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": {} } } } } } } } } }, "delete": { "operationId": "deleteChatSession", "summary": "Delete a chat session", "tags": [ "Chat" ], "description": "Soft-deletes the session by setting status='archived'. The row stays in the database for chat_agent_log foreign-key integrity but is excluded from the session list and returns 404 from GET /session/:id thereafter. Ownership is enforced — non-owners receive 404, mirroring GET /session/:id.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" }, "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" } ] }