{"openapi":"3.1.0","info":{"title":"OpenSanctions (BYOK) API","version":"0.1.0","description":"OpenSanctions (BYOK) lets an AI assistant read your own OpenSanctions data through the OpenSanctions API with a key you supply (OpenSanctions API key). Read-only: 7 tools (search_entities, screen_entity, get_entity, list_adjacent_entities, list_adjacent_by_property, list_datasets, list_matching_algorithms). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-opensanctions.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-opensanctions/docs"},"termsOfService":"https://connectorbay.com/byok-opensanctions/terms"},"servers":[{"url":"https://byok-opensanctions.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-opensanctions/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_entities":{"post":{"operationId":"search_entities","summary":"Full-text search for people, companies and other entities in sanctions, PEP and watchlist datasets. Good for lookups by ","description":"Full-text search for people, companies and other entities in sanctions, PEP and watchlist datasets. Good for lookups by name; use screen_entity for screening decisions. Use for \"Is there a sanctions or PEP entry for Ilham Aliyev\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"Dataset or collection to use: 'default' (everything), 'sanctions', 'peps', or a single source such as 'us_ofac_sdn'.","maxLength":200,"title":"Dataset","type":"string"},"q":{"description":"Search text; quotes force an exact phrase and ~ allows spelling variants, for example '\"Ilham Aliyev\"'.","maxLength":300,"title":"Q","type":"string"},"schema":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities of this type, for example Person, Company or Vessel (default: all kinds).","title":"Schema"},"fuzzy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to allow fuzzy matching in the query.","title":"Fuzzy"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 500, default 10).","title":"Limit"},"offset":{"anyOf":[{"maximum":9499,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 to 9499).","title":"Offset"}},"required":["dataset","q"],"title":"search_entitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/screen_entity":{"post":{"operationId":"screen_entity","summary":"Screen a person or company against a dataset by describing it (name, birth date, country). Returns scored candidate matc","description":"Screen a person or company against a dataset by describing it (name, birth date, country). Returns scored candidate matches with a match flag and score. Only asks a question of the database. Use for \"Screen the person Jane Doe born 1970-01-01 from Russia against sanctions lists\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"Dataset or collection to use: 'default' (everything), 'sanctions', 'peps', or a single source such as 'us_ofac_sdn'.","maxLength":200,"title":"Dataset","type":"string"},"name":{"description":"Full name of the person or company to screen.","maxLength":200,"title":"Name","type":"string"},"schema":{"description":"Entity type: Person, Company, Organization, LegalEntity, Vessel or Airplane.","enum":["Person","Company","Organization","LegalEntity","Vessel","Airplane"],"title":"Schema","type":"string"},"birth_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Birth date as YYYY-MM-DD, YYYY-MM or YYYY, for people.","title":"Birth Date"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter country code of nationality or registration, for example 'ru'.","title":"Country"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many candidate matches to return (default 5).","title":"Limit"},"threshold":{"anyOf":[{"maximum":1,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Score from 0 to 1 above which a candidate counts as a match; leave empty for the server default.","title":"Threshold"}},"required":["dataset","name","schema"],"title":"screen_entityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_entity":{"post":{"operationId":"get_entity","summary":"Get the full record of one entity by ID: names, birth data, countries, topics, datasets that mention it and, if nested i","description":"Get the full record of one entity by ID: names, birth data, countries, topics, datasets that mention it and, if nested is true, related sanctions, ownership and family entities. Use for \"Show the full OpenSanctions record for entity Q7747\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_id":{"description":"Entity ID from a search or match answer, for example 'Q7747' or 'NK-aU5ybkbRFJucf8YMwsJvDw'.","maxLength":200,"title":"Entity Id","type":"string"},"nested":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include adjacent entities (sanctions, ownership, family) inline; the answer can be large.","title":"Nested"}},"required":["entity_id"],"title":"get_entityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_adjacent_entities":{"post":{"operationId":"list_adjacent_entities","summary":"List entities linked to a given entity (sanctions, ownership, family, passports), grouped by relationship, with a count ","description":"List entities linked to a given entity (sanctions, ownership, family, passports), grouped by relationship, with a count for each group. Use for \"What entities are linked to entity Q7747\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_id":{"description":"Entity ID from a search or match answer, for example 'Q7747' or 'NK-aU5ybkbRFJucf8YMwsJvDw'.","maxLength":200,"title":"Entity Id","type":"string"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per relationship group (1 to 500, default 10).","title":"Limit"},"offset":{"anyOf":[{"maximum":9499,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 to 9499).","title":"Offset"}},"required":["entity_id"],"title":"list_adjacent_entitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_adjacent_by_property":{"post":{"operationId":"list_adjacent_by_property","summary":"Page through the entities linked to a given entity through one property, for example 'sanctions', 'ownershipOwner' or 'f","description":"Page through the entities linked to a given entity through one property, for example 'sanctions', 'ownershipOwner' or 'familyPerson'. Use for \"List the sanctions entries attached to entity Q7747\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_id":{"description":"Entity ID from a search or match answer, for example 'Q7747' or 'NK-aU5ybkbRFJucf8YMwsJvDw'.","maxLength":200,"title":"Entity Id","type":"string"},"property_name":{"description":"Property that links to related entities, for example 'sanctions' or 'ownershipAsset'.","maxLength":200,"title":"Property Name","type":"string"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results to return (1 to 500, default 10).","title":"Limit"},"offset":{"anyOf":[{"maximum":9499,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 to 9499).","title":"Offset"}},"required":["entity_id","property_name"],"title":"list_adjacent_by_propertyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasets":{"post":{"operationId":"list_datasets","summary":"List the datasets the API can search (sanctions lists, PEP lists and others) with title, publisher summary, entity count","description":"List the datasets the API can search (sanctions lists, PEP lists and others) with title, publisher summary, entity counts and last update. Use for \"Which sanctions datasets does OpenSanctions cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_matching_algorithms":{"post":{"operationId":"list_matching_algorithms","summary":"List the scoring algorithms screen_entity can use, with the default and best-quality choice and a description of each. U","description":"List the scoring algorithms screen_entity can use, with the default and best-quality choice and a description of each. Use for \"Which matching algorithms does OpenSanctions offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_matching_algorithmsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}