{
 "openapi": "3.0.3",
 "info": {
  "title": "Crown Intelligence data API",
  "version": "2026-10-04",
  "description": "Read-only JSON API over Crown Intelligence sanctions, PEP, debarment and enforcement records: entity matching, entity look-up, search, facets, sources, programmes, countries, collection catalogue and register exports. No API key is required today; see /docs/api/authentication.html. Guides: /docs/api/.",
  "contact": {
   "name": "Crown Intelligence support",
   "email": "support@crownintelligence.net"
  },
  "termsOfService": "/legal/terms"
 },
 "servers": [
  {
   "url": "https://api.crownintelligence.net",
   "description": "Production (as documented on developers.html)"
  },
  {
   "url": "/",
   "description": "This site"
  }
 ],
 "tags": [
  {
   "name": "Matching"
  },
  {
   "name": "Entities"
  },
  {
   "name": "Search"
  },
  {
   "name": "Catalogue"
  },
  {
   "name": "Reference"
  }
 ],
 "paths": {
  "/api/match/{collection}": {
   "post": {
    "tags": [
     "Matching"
    ],
    "summary": "Score parties against a collection",
    "operationId": "match",
    "description": "Up to 20 named queries per request. Each result carries a score from 0 to 1, a match flag (score at or above threshold) and a feature-by-feature explanation. Request bodies are not stored.",
    "parameters": [
     {
      "name": "collection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "default",
        "sanctions",
        "peps",
        "crime",
        "maritime"
       ]
      },
      "description": "Collection to search."
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Results per query, 1 to 50.",
      "schema": {
       "type": "integer",
       "default": 5,
       "minimum": 1,
       "maximum": 50
      }
     },
     {
      "name": "threshold",
      "in": "query",
      "description": "Score at which `match` is true.",
      "schema": {
       "type": "number",
       "default": 0.75,
       "minimum": 0,
       "maximum": 1
      }
     },
     {
      "name": "algorithm",
      "in": "query",
      "description": "Scoring method (`best` means the default).",
      "schema": {
       "type": "string",
       "default": "standard",
       "enum": [
        "standard",
        "name-only",
        "best"
       ]
      }
     },
     {
      "name": "topics",
      "in": "query",
      "description": "Risk topics to keep (repeat or comma-separate). OR within, AND with other filters.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string",
        "enum": [
         "sanction",
         "role.pep",
         "debarment",
         "reg.action"
        ]
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "include_dataset",
      "in": "query",
      "description": "Register names to keep (repeat for several), as in /api/sources and result `datasets`.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "exclude_dataset",
      "in": "query",
      "description": "Register names to leave out (repeat for several).",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "changed_since",
      "in": "query",
      "description": "Only records added or changed on or after this ISO 8601 date or time (added = first collected; changed = an export build saw the published record change). For scheduled re-screening.",
      "schema": {
       "type": "string",
       "example": "2026-10-01"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MatchRequest"
       },
       "example": {
        "queries": {
         "q1": {
          "schema": "Person",
          "properties": {
           "name": [
            "Igor Putin"
           ],
           "birthDate": [
            "1953"
           ],
           "nationality": [
            "ru"
           ]
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Scored results per query",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MatchResponse"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "405": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests (only when the optional request limit is switched on)",
      "headers": {
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/reconcile/{collection}": {
   "get": {
    "tags": [
     "Matching"
    ],
    "summary": "OpenRefine reconciliation (service manifest, or queries=)",
    "operationId": "reconcileGet",
    "parameters": [
     {
      "name": "collection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "default",
        "sanctions",
        "peps",
        "crime",
        "maritime"
       ]
      },
      "description": "Collection to search."
     },
     {
      "name": "queries",
      "in": "query",
      "description": "JSON object of reconciliation queries (Reconciliation API 0.2). Omit for the service manifest.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Manifest or reconciliation results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Matching"
    ],
    "summary": "OpenRefine reconciliation (form or JSON body with queries)",
    "operationId": "reconcilePost",
    "parameters": [
     {
      "name": "collection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "default",
        "sanctions",
        "peps",
        "crime",
        "maritime"
       ]
      },
      "description": "Collection to search."
     }
    ],
    "requestBody": {
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "queries": {
          "type": "string"
         }
        }
       }
      },
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "queries": {
          "type": "object"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Reconciliation results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/algorithms": {
   "get": {
    "tags": [
     "Matching"
    ],
    "summary": "Scoring methods, features, constants and topics",
    "operationId": "algorithms",
    "responses": {
     "200": {
      "description": "Algorithms",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "default": {
           "type": "string"
          },
          "threshold": {
           "type": "number"
          },
          "algorithms": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Algorithm"
           }
          },
          "constants": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "topics": {
           "type": "object"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/entity/{id}": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "A record by ID, or a merged entity by entity_id",
    "operationId": "entity",
    "description": "A numeric ID returns that record with `related` records, nested `listings` and `merged_entity_url`. A UUID returns the merged entity across registers. A record that is no longer active but whose merged entity is answers 308 to the merged entity.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Record ID (integer or crown-<id>) or merged entity ID (UUID or crown-e-<uuid>)."
     },
     {
      "name": "nested",
      "in": "query",
      "description": "false omits related records, listings and records. With format=ftm, true nests the Sanction entity.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "format",
      "in": "query",
      "description": "ftm returns the record as a FollowTheMoney entity (same shape as entities.ftm.json).",
      "schema": {
       "type": "string",
       "enum": [
        "ftm"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Record or merged entity",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/Record"
          },
          {
           "$ref": "#/components/schemas/MergedEntity"
          }
         ]
        }
       }
      }
     },
     "308": {
      "description": "Record no longer active; Location points to its merged entity"
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/entity": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "Record or merged entity (query form)",
    "operationId": "entityQuery",
    "parameters": [
     {
      "name": "id",
      "in": "query",
      "description": "Record ID.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "entity_id",
      "in": "query",
      "description": "Merged entity ID (UUID).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "nested",
      "in": "query",
      "description": "false omits nested data.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "format",
      "in": "query",
      "description": "ftm for a FollowTheMoney entity.",
      "schema": {
       "type": "string",
       "enum": [
        "ftm"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Record or merged entity",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "308": {
      "description": "See /api/entity/{id}"
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/search": {
   "get": {
    "tags": [
     "Search"
    ],
    "summary": "Search all records by name with filters",
    "operationId": "search",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Name, at least 2 characters; optional when a filter is set.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "scope",
      "in": "query",
      "description": "Collection.",
      "schema": {
       "type": "string",
       "enum": [
        "default",
        "sanctions",
        "peps",
        "crime",
        "maritime"
       ]
      }
     },
     {
      "name": "type",
      "in": "query",
      "description": "Entity type, e.g. INDIVIDUAL, COMPANY, VESSEL.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "list_type",
      "in": "query",
      "description": "SANCTION, PEP, DEBARMENT, TAX_WARRANT or INSOLVENCY.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topics",
      "in": "query",
      "description": "Risk topics to keep (repeat or comma-separate). OR within, AND with other filters.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string",
        "enum": [
         "sanction",
         "role.pep",
         "debarment",
         "reg.action"
        ]
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "include_dataset",
      "in": "query",
      "description": "Register names to keep (repeat for several), as in /api/sources and result `datasets`.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "exclude_dataset",
      "in": "query",
      "description": "Register names to leave out (repeat for several).",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "source",
      "in": "query",
      "description": "One register name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "nationality",
      "in": "query",
      "description": "Two-letter country code.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "dob",
      "in": "query",
      "description": "Birth date prefix YYYY, YYYY-MM or YYYY-MM-DD.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "program",
      "in": "query",
      "description": "Exact programme.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "description": "first_seen for newest first.",
      "schema": {
       "type": "string",
       "enum": [
        "first_seen"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Results per page, up to 50.",
      "schema": {
       "type": "integer",
       "default": 25,
       "maximum": 50
      }
     },
     {
      "name": "page",
      "in": "query",
      "description": "Page from 1.",
      "schema": {
       "type": "integer",
       "default": 1
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Record offset (instead of page).",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "changed_since",
      "in": "query",
      "description": "Only records added or changed on or after this ISO 8601 date or time (added = first collected; changed = an export build saw the published record change). For scheduled re-screening.",
      "schema": {
       "type": "string",
       "example": "2026-10-01"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Search results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResponse"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/search/{collection}": {
   "get": {
    "tags": [
     "Search"
    ],
    "summary": "Search one collection",
    "operationId": "searchCollection",
    "description": "Same parameters as /api/search; the collection replaces `scope`.",
    "parameters": [
     {
      "name": "collection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "default",
        "sanctions",
        "peps",
        "crime",
        "maritime"
       ]
      },
      "description": "Collection to search."
     },
     {
      "name": "q",
      "in": "query",
      "description": "Name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topics",
      "in": "query",
      "description": "Risk topics to keep (repeat or comma-separate). OR within, AND with other filters.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string",
        "enum": [
         "sanction",
         "role.pep",
         "debarment",
         "reg.action"
        ]
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "include_dataset",
      "in": "query",
      "description": "Register names to keep (repeat for several), as in /api/sources and result `datasets`.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "exclude_dataset",
      "in": "query",
      "description": "Register names to leave out (repeat for several).",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": true
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Up to 50.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "changed_since",
      "in": "query",
      "description": "Only records added or changed on or after this ISO 8601 date or time (added = first collected; changed = an export build saw the published record change). For scheduled re-screening.",
      "schema": {
       "type": "string",
       "example": "2026-10-01"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Search results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResponse"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/facets": {
   "get": {
    "tags": [
     "Search"
    ],
    "summary": "Counts by list type, entity type, country and register",
    "operationId": "facets",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "scope",
      "in": "query",
      "description": "Collection.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "list_type",
      "in": "query",
      "description": "List type.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "type",
      "in": "query",
      "description": "Entity type.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "nationality",
      "in": "query",
      "description": "Country code.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "source",
      "in": "query",
      "description": "Register.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "program",
      "in": "query",
      "description": "Programme.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Facet counts",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/catalog": {
   "get": {
    "tags": [
     "Catalogue"
    ],
    "summary": "Collections with figures, version and files",
    "operationId": "catalog",
    "responses": {
     "200": {
      "description": "Collections",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Catalog"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/overview": {
   "get": {
    "tags": [
     "Catalogue"
    ],
    "summary": "Headline figures",
    "operationId": "overview",
    "responses": {
     "200": {
      "description": "Figures",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "description": "Registry totals (company_registry_records, registered_person_records, beneficial_owner_records, security_records, vessel_records, employment_disclosure_records, underlying_records) are exact counts taken in the background every 6 hours; counts_exact and registry_counts_at say so. Until the first count finishes they are planner estimates and counts_exact is false."
   }
  },
  "/api/status": {
   "get": {
    "tags": [
     "Catalogue"
    ],
    "summary": "Service check with record counts",
    "operationId": "status",
    "responses": {
     "200": {
      "description": "Status",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/collection": {
   "get": {
    "tags": [
     "Catalogue"
    ],
    "summary": "Figures for a list type within a scope",
    "operationId": "collection",
    "parameters": [
     {
      "name": "type",
      "in": "query",
      "description": "SANCTION, PEP or DEBARMENT.",
      "schema": {
       "type": "string"
      },
      "required": true
     },
     {
      "name": "scope",
      "in": "query",
      "description": "default, sanctions, peps, crime, maritime, kyb or securities.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Figures",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/sources": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Registers with publisher, country, status and licence policy",
    "operationId": "sources",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Text filter.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "list_type",
      "in": "query",
      "description": "List type.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "description": "Page.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Up to 100.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "description": "name (default) or first_seen (newest registers first).",
      "schema": {
       "type": "string",
       "enum": [
        "name",
        "first_seen"
       ]
      }
     },
     {
      "name": "latest",
      "in": "query",
      "description": "true is the same as sort=first_seen.",
      "schema": {
       "type": "boolean"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Registers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "description": "Each register carries first_seen (when its earliest record was first collected) and format (source file format, where recorded)."
   }
  },
  "/api/source": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "One register with figures, types, countries, programmes and recent records",
    "operationId": "source",
    "parameters": [
     {
      "name": "name",
      "in": "query",
      "description": "Register name.",
      "schema": {
       "type": "string"
      },
      "required": true
     }
    ],
    "responses": {
     "200": {
      "description": "Register",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "description": "Adds format (source file format), first_seen, last_change (latest record added to or removed from the register), version and run_id (the last load run, YYYYMMDDHHMMSS), run {last_run_at, version, status, row_count, method, cadence_hours} and changes {last_added, last_removed, added_7d, added_30d, removed_7d, removed_30d, days:[{date, added, removed}] for 90 days}."
   }
  },
  "/api/programs": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Programmes with record counts",
    "operationId": "programs",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Text filter.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "list_type",
      "in": "query",
      "description": "List type or ALL.",
      "schema": {
       "type": "string",
       "default": "SANCTION"
      }
     },
     {
      "name": "page",
      "in": "query",
      "description": "Page.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Up to 100.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Programmes",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/countries": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Record counts by country",
    "operationId": "countries",
    "responses": {
     "200": {
      "description": "Countries",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/licences": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Registers by licence classification",
    "operationId": "licences",
    "parameters": [
     {
      "name": "offer",
      "in": "query",
      "description": "download, sale or none.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Licence classification",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/export": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Download one register published for download",
    "operationId": "export",
    "parameters": [
     {
      "name": "source",
      "in": "query",
      "description": "Register name.",
      "schema": {
       "type": "string"
      },
      "required": true
     },
     {
      "name": "format",
      "in": "query",
      "description": "csv or jsonl.",
      "schema": {
       "type": "string",
       "default": "csv",
       "enum": [
        "csv",
        "jsonl"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "CSV or JSON lines",
      "content": {
       "text/csv": {},
       "application/x-ndjson": {}
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/screen": {
   "post": {
    "tags": [
     "Matching"
    ],
    "summary": "Legacy name look-up (use /api/match)",
    "deprecated": true,
    "operationId": "screen",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "nationality": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Matches",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/registries": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "KYB registries with exact record counts",
    "operationId": "registries",
    "description": "Company, registered-person, beneficial-owner, security, vessel and employment-disclosure registers: publisher, jurisdiction, source link, licence link and clearance (commercial), exact records, number of jurisdictions and the top ten, last_processed and version (load time, YYYYMMDDHHMMSS). One row per register and kind. Counts are refreshed every 6 hours (counts_at). Also published as /downloads/meta/registries.json.",
    "parameters": [
     {
      "name": "kind",
      "in": "query",
      "description": "Registry kind.",
      "schema": {
       "type": "string",
       "enum": [
        "company",
        "person",
        "beneficial_owner",
        "security",
        "vessel",
        "employment_disclosure"
       ]
      }
     },
     {
      "name": "name",
      "in": "query",
      "description": "One register by name (404 when unknown).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "q",
      "in": "query",
      "description": "Text filter on name, publisher and jurisdiction.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "jurisdiction",
      "in": "query",
      "description": "ISO code: registers whose jurisdiction (or one of their top ten) it is.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Registries",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/registries/countries": {
   "get": {
    "tags": [
     "Reference"
    ],
    "summary": "Registry records per jurisdiction",
    "operationId": "registryCountries",
    "description": "Precomputed per-jurisdiction counts across the registries: records, registers and records by kind. XX means the register gives no jurisdiction.",
    "parameters": [
     {
      "name": "kind",
      "in": "query",
      "description": "Registry kind.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "register",
      "in": "query",
      "description": "One register by name.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Jurisdictions",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/statements": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "Statements (lineage) for one entity",
    "operationId": "statements",
    "description": "The statement rows of statements.csv for one merged entity or record, generated live: id, entity_id, canonical_id, prop, prop_type, schema, value, dataset, lang, original_value, first_seen, last_seen. For everything use the bulk statements.csv.",
    "parameters": [
     {
      "name": "canonical_id",
      "in": "query",
      "description": "Merged entity: crown-e-<uuid>.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "entity_id",
      "in": "query",
      "description": "Merged entity UUID.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "id",
      "in": "query",
      "description": "Record: crown-<number> or the number.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "dataset",
      "in": "query",
      "description": "Dataset slug or register name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "prop",
      "in": "query",
      "description": "Properties to keep (repeat or comma-separate).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Up to 5000.",
      "schema": {
       "type": "integer",
       "default": 1000,
       "maximum": 5000
      }
     },
     {
      "name": "format",
      "in": "query",
      "description": "csv returns text/csv with the statements.csv header.",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Statements",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "The database is temporarily unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "detail": {
      "type": "string"
     }
    },
    "required": [
     "error"
    ]
   },
   "Query": {
    "type": "object",
    "properties": {
     "schema": {
      "type": "string",
      "enum": [
       "Person",
       "Company",
       "Organization",
       "LegalEntity",
       "Vessel",
       "Airplane"
      ],
      "default": "LegalEntity"
     },
     "properties": {
      "type": "object",
      "description": "Lists of up to 5 strings. Aliases: query=name, dob=birthDate, country/countries/jurisdiction/flag=nationality, imo=imoNumber. mmsi is matched as an identifier like imoNumber.",
      "properties": {
       "name": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "birthDate": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "nationality": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "country": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "imoNumber": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "mmsi": {
        "type": "array",
        "items": {
         "type": "string"
        },
        "description": "Nine-digit MMSI (vessels)."
       }
      }
     }
    }
   },
   "MatchRequest": {
    "type": "object",
    "description": "Named queries, or a single query (answered as q1).",
    "properties": {
     "queries": {
      "type": "object",
      "maxProperties": 20,
      "additionalProperties": {
       "$ref": "#/components/schemas/Query"
      }
     }
    }
   },
   "Feature": {
    "type": "object",
    "properties": {
     "feature": {
      "type": "string"
     },
     "explanation": {
      "type": "string"
     },
     "score": {
      "type": "number"
     },
     "weight": {
      "type": "number"
     },
     "matched_name": {
      "type": "string"
     }
    }
   },
   "MatchResult": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "caption": {
      "type": "string"
     },
     "schema": {
      "type": "string"
     },
     "score": {
      "type": "number"
     },
     "match": {
      "type": "boolean"
     },
     "features": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Feature"
      }
     },
     "source": {
      "type": "string"
     },
     "datasets": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "list_type": {
      "type": "string"
     },
     "programme": {
      "type": "string",
      "nullable": true
     },
     "birth_date": {
      "type": "string",
      "nullable": true
     },
     "nationality": {
      "type": "string",
      "nullable": true
     },
     "imo": {
      "type": "string",
      "nullable": true
     },
     "aliases": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "merged_entity": {
      "type": "string",
      "nullable": true
     },
     "first_seen": {
      "type": "string",
      "format": "date-time"
     },
     "last_seen": {
      "type": "string",
      "format": "date-time"
     },
     "url": {
      "type": "string"
     },
     "mmsi": {
      "type": "string",
      "nullable": true,
      "description": "MMSI where the record gives one."
     }
    }
   },
   "MatchResponse": {
    "type": "object",
    "properties": {
     "collection": {
      "type": "string"
     },
     "algorithm": {
      "type": "string"
     },
     "threshold": {
      "type": "number"
     },
     "limit": {
      "type": "integer"
     },
     "filters": {
      "type": "object",
      "properties": {
       "topics": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "include_dataset": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "exclude_dataset": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "responses": {
      "type": "object",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "status": {
         "type": "integer"
        },
        "query": {
         "type": "object"
        },
        "total": {
         "type": "integer"
        },
        "error": {
         "type": "string"
        },
        "results": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/MatchResult"
         }
        }
       }
      }
     },
     "checked_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Listing": {
    "type": "object",
    "properties": {
     "record_id": {
      "type": "integer"
     },
     "register": {
      "type": "string"
     },
     "list_type": {
      "type": "string"
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "programme": {
      "type": "string",
      "nullable": true
     },
     "listed_on": {
      "type": "string",
      "nullable": true
     },
     "delisted_at": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "type": "string",
      "nullable": true
     },
     "source_url": {
      "type": "string",
      "nullable": true
     },
     "first_seen": {
      "type": "string"
     },
     "last_seen": {
      "type": "string"
     },
     "last_change": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    }
   },
   "Record": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "source": {
      "type": "string"
     },
     "register": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "alt_names": {
      "type": "string",
      "nullable": true
     },
     "program": {
      "type": "string",
      "nullable": true
     },
     "list_type": {
      "type": "string"
     },
     "entity_type": {
      "type": "string"
     },
     "dob": {
      "type": "string",
      "nullable": true
     },
     "dob_precision": {
      "type": "string",
      "nullable": true
     },
     "nationality": {
      "type": "string",
      "nullable": true
     },
     "entity_id": {
      "type": "string",
      "nullable": true
     },
     "first_seen": {
      "type": "string"
     },
     "loaded_at": {
      "type": "string"
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "merged_entity_url": {
      "type": "string"
     },
     "related": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "listings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Listing"
      }
     },
     "last_change": {
      "type": "string",
      "format": "date-time",
      "description": "When the published record last changed (tracked by the export builds from 2026-10-04), else when it was first collected."
     },
     "last_change_basis": {
      "type": "string"
     },
     "vessel": {
      "type": "object",
      "description": "Vessel details read from the publisher's text, present when any is found.",
      "properties": {
       "flag": {
        "type": "string",
        "nullable": true,
        "description": "ISO 3166-1 alpha-2"
       },
       "flag_name": {
        "type": "string",
        "nullable": true
       },
       "past_flags": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "past_flag_names": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "mmsi": {
        "type": "string",
        "nullable": true
       }
      }
     }
    }
   },
   "MergedEntity": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "entity_id": {
      "type": "string"
     },
     "caption": {
      "type": "string"
     },
     "schema": {
      "type": "string"
     },
     "properties": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     },
     "datasets": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "first_seen": {
      "type": "string"
     },
     "last_seen": {
      "type": "string"
     },
     "referents": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "listings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Listing"
      }
     },
     "records": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "last_change": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    }
   },
   "SearchResponse": {
    "type": "object",
    "properties": {
     "query": {
      "type": "string"
     },
     "page": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     },
     "total": {
      "type": "integer"
     },
     "filters": {
      "type": "object"
     },
     "results": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   },
   "Algorithm": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string"
     },
     "label": {
      "type": "string"
     },
     "default": {
      "type": "boolean"
     },
     "description": {
      "type": "string"
     },
     "features": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "feature": {
         "type": "string"
        },
        "effect": {
         "type": "string"
        },
        "description": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "Catalog": {
    "type": "object",
    "properties": {
     "publisher": {
      "type": "string"
     },
     "generated_at": {
      "type": "string"
     },
     "collections": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "name": {
         "type": "string"
        },
        "title": {
         "type": "string"
        },
        "version": {
         "type": "string"
        },
        "records": {
         "type": "integer"
        },
        "distinct_entities": {
         "type": "integer"
        },
        "sources": {
         "type": "integer"
        },
        "last_change": {
         "type": "string"
        },
        "last_processed": {
         "type": "string"
        },
        "links": {
         "type": "object"
        },
        "files": {
         "type": "array",
         "items": {
          "type": "object"
         }
        }
       }
      }
     }
    }
   }
  }
 }
}