{ "openapi": "3.1.0", "info": { "title": "Truespar LEI API", "description": "A free, open API over the GLEIF Level 1 golden copy: every legal entity in the world that holds a Legal Entity Identifier, about 3.4 million of them, redownloaded and reingested daily.\n\nNo account, no key. Rate-limited per IP; responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`, and a 429 carries `Retry-After`.\n\nThe data is GLEIF's, published under CC0. Truespar reproduces it as-is and adds no restriction of its own - and no correction either: if a record is wrong or stale upstream, it is wrong here. Search is powered by Torque, Truespar's search engine, on Truespar hardware.\n\nAn MCP endpoint over the same dataset is available at `/mcp` (Streamable HTTP), with the tools `search_legal_entities` and `get_legal_entity`.", "contact": { "name": "Truespar", "url": "https://truespar.com" }, "license": { "name": "Data: CC0 1.0 (GLEIF)", "url": "https://www.gleif.org/en/meta/lei-data-terms-of-use" }, "version": "1.0.0" }, "servers": [ { "url": "https://lei.truespar.com", "description": "Production" } ], "paths": { "/v1/entities": { "get": { "tags": [ "entities" ], "summary": "Search legal entities.", "description": "Free-text search over the GLEIF golden copy, with optional filters and\nfacet counts. Results are ranked by relevance; the collection has no\nsortable fields, so there is no sort parameter.", "operationId": "search_entities", "parameters": [ { "name": "q", "in": "query", "description": "Free-text query, typo tolerant. Omit to match everything and filter\nonly.", "required": false, "schema": { "type": "string" }, "example": "volvo" }, { "name": "fields", "in": "query", "description": "Which fields the query searches: `all` (default), `name`, `address`,\n`lei`.", "required": false, "schema": { "type": "string" }, "example": "name" }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country of the legal address. Comma-separate for OR.", "required": false, "schema": { "type": "string" }, "example": "SE" }, { "name": "jurisdiction", "in": "query", "description": "ISO 3166 legal jurisdiction. Comma-separate for OR.", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Entity status: `ACTIVE` or `INACTIVE`.", "required": false, "schema": { "type": "string" }, "example": "ACTIVE" }, { "name": "registrationStatus", "in": "query", "description": "LEI registration status, e.g. `ISSUED`, `LAPSED`, `RETIRED`.", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "GLEIF entity category, e.g. `GENERAL`, `FUND`, `BRANCH`.", "required": false, "schema": { "type": "string" }, "example": "FUND" }, { "name": "legalForm", "in": "query", "description": "ISO 20275 Entity Legal Form code.", "required": false, "schema": { "type": "string" } }, { "name": "managingLou", "in": "query", "description": "LEI of the managing Local Operating Unit.", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "facets", "in": "query", "description": "Comma-separated facets to count alongside the results. Facetable:\n`country`, `jurisdiction`, `status`, `registrationStatus`, `category`.", "required": false, "schema": { "type": "string" }, "example": "country,status" }, { "name": "page", "in": "query", "description": "1-based page number. Default 1.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Page size. Default 20, maximum 100.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "A page of matching entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPage" } } } }, "400": { "description": "An unknown filter, facet or field, or too deep a page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-IP rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/entities/{lei}": { "get": { "tags": [ "entities" ], "summary": "Fetch one legal entity by LEI.", "description": "The LEI is validated before the lookup, including its ISO 17442 check\ndigits, so a mistyped identifier returns 400 rather than a 404 that leaves\nyou unsure whether the entity exists.", "operationId": "get_entity", "parameters": [ { "name": "lei", "in": "path", "description": "ISO 17442 Legal Entity Identifier", "required": true, "schema": { "type": "string" }, "example": "2138006AOPRVN2HX7829" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalEntity" } } } }, "400": { "description": "The LEI is malformed or fails its checksum", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "No entity with that LEI in the dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-IP rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/facets/{field}": { "get": { "tags": [ "reference" ], "summary": "List the values of one facet across the whole dataset.", "operationId": "list_facet", "parameters": [ { "name": "field", "in": "path", "description": "One of: country, jurisdiction, status, registrationStatus, category", "required": true, "schema": { "type": "string" }, "example": "country" } ], "responses": { "200": { "description": "Facet values with counts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } } } } }, "400": { "description": "Not a facetable field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-IP rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/stats": { "get": { "tags": [ "reference" ], "summary": "Dataset size, provenance and the timings of the last daily reload.", "operationId": "dataset_stats", "responses": { "200": { "description": "Dataset statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetStats" } } } }, "429": { "description": "Per-IP rate limit exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "ApiError": { "type": "object", "description": "A single error, the shape every non-2xx response takes.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "An LEI is 20 characters, got 8" } } }, "DatasetStats": { "type": "object", "description": "Dataset size and the timings of the last daily reload.", "required": [ "records", "source", "license" ], "properties": { "downloadSeconds": { "type": [ "number", "null" ], "format": "double", "description": "Seconds spent downloading the golden copy." }, "ingestSeconds": { "type": [ "number", "null" ], "format": "double", "description": "Seconds spent streaming it into a fresh collection." }, "license": { "type": "string" }, "published": { "type": [ "string", "null" ], "description": "GLEIF publication timestamp of the loaded file." }, "records": { "type": "integer", "format": "int64", "description": "Entities currently searchable.", "example": 3396479 }, "source": { "type": "string", "description": "Where the data comes from and what it is." } } }, "Facet": { "type": "object", "description": "Counts for one facet field across everything matching the query.", "required": [ "field", "values" ], "properties": { "field": { "type": "string", "description": "The request parameter name, e.g. `country`.", "example": "country" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } } } }, "FacetValue": { "type": "object", "description": "One value of a facet, with how many entities carry it.", "required": [ "value", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "example": 42513 }, "value": { "type": "string", "example": "SE" } } }, "LegalEntity": { "type": "object", "description": "One legal entity from the GLEIF Level 1 golden copy.", "required": [ "lei" ], "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country of the legal address.", "example": "GB" }, "entityCategory": { "type": [ "string", "null" ], "description": "GLEIF entity category, e.g. `GENERAL`, `FUND`, `BRANCH`.", "example": "GENERAL" }, "entityStatus": { "type": [ "string", "null" ], "description": "Whether the entity itself is active: `ACTIVE` or `INACTIVE`.", "example": "ACTIVE" }, "hqAddress": { "type": [ "string", "null" ], "description": "First line of the headquarters address, where it differs." }, "jurisdiction": { "type": [ "string", "null" ], "description": "ISO 3166 code of the legal jurisdiction, which may differ from `country`." }, "lastUpdatedAt": { "type": [ "string", "null" ], "description": "When the record was last updated upstream." }, "legalAddress": { "type": [ "string", "null" ], "description": "First line of the registered legal address." }, "legalForm": { "type": [ "string", "null" ], "description": "ISO 20275 Entity Legal Form code, e.g. `H0PO`.", "example": "H0PO" }, "legalName": { "type": [ "string", "null" ], "description": "Registered legal name.", "example": "RING AUTOMOTIVE LIMITED" }, "lei": { "type": "string", "description": "ISO 17442 Legal Entity Identifier, 20 characters.", "example": "2138006AOPRVN2HX7829" }, "managingLou": { "type": [ "string", "null" ], "description": "LEI of the Local Operating Unit that maintains this record." }, "postalCode": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ], "description": "ISO 3166-2 subdivision, e.g. `GB-LDS`.", "example": "GB-LDS" }, "registeredAt": { "type": [ "string", "null" ], "description": "When the LEI was first issued." }, "registrationStatus": { "type": [ "string", "null" ], "description": "Status of the LEI registration, e.g. `ISSUED`, `LAPSED`, `RETIRED`.\nAn entity can be `ACTIVE` while its registration has `LAPSED`, which is\nsimply an unrenewed record.", "example": "LAPSED" } } }, "SearchPage": { "type": "object", "description": "A page of search results.", "required": [ "found", "outOf", "page", "limit", "searchTimeMs", "results" ], "properties": { "facets": { "type": "array", "items": { "$ref": "#/components/schemas/Facet" }, "description": "Present only when `facets` was requested." }, "found": { "type": "integer", "format": "int64", "description": "Entities matching the query and filters.", "example": 85 }, "limit": { "type": "integer", "format": "int64", "description": "Page size that was applied, after clamping." }, "outOf": { "type": "integer", "format": "int64", "description": "Total entities in the dataset, ignoring the query.", "example": 3396479 }, "page": { "type": "integer", "format": "int64", "description": "1-based page number that was returned." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LegalEntity" } }, "searchTimeMs": { "type": "integer", "format": "int64", "description": "How long Torque spent on the search." } } } } }, "tags": [ { "name": "entities", "description": "Search and retrieve legal entities" }, { "name": "reference", "description": "Facet vocabularies and dataset statistics" } ] }