{ "openapi": "3.0.3", "info": { "title": "NOSIBLE Atlas V2.0 API", "version": "2.0", "description": "Public Atlas V2.0 API contract. Examples illustrate responses and do not require optional fields to be present. Existing API URLs remain supported." }, "servers": [ { "url": "https://nosible.world" } ], "externalDocs": { "url": "https://docs.nosible.com/" }, "paths": { "/api/v2.0/atlas/graphs/prompt": { "post": { "operationId": "atlas_prompt", "summary": "By prompt", "description": "Ask in plain English and get a graph back, with a written explanation.\n\nUse By prompt when you would rather describe the graph than build it from parameters. A language model plans the query, Atlas runs it on the graph, and the explanation is written only from what the graph contains. Expect 5 to 25 seconds. Pass the returned session to refine the same graph in a follow-up question. A follow-up keeps the session's as_of and from unless it sends new ones, and each date you send replaces only itself for the later turns; window_source says where this turn's window came from. A question about ownership uses min_support 10, as By ownership does, unless the prompt states a threshold of its own. A session belongs to the API key that created it, and a session can run one prompt at a time. The graph and the explanation vary from run to run, because the model plans each answer afresh: the example is one real response, which the same request will not repeat word for word.", "tags": [ "BUILD GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-prompt" }, "x-nosible-reference-pages": [ "atlas-prompt" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "JSON response, or NDJSON when stream=true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "graph": { "type": "object", "properties": { "count": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "object": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "predicate": { "type": "string" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "number" } }, "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "focus": { "type": "boolean" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, count, total, truncated}. nodes carry focus: true for the entities you asked about; edges are relationships, strongest first; total counts edges before the limit." }, "id": { "type": "string", "description": "Id of this answer (ap_ followed by 16 hex characters)." }, "message": { "type": "string", "description": "The explanation of the graph, in Markdown." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered." }, "schema": { "type": "string", "description": "Response schema name." }, "session": { "type": "string", "description": "Session id to send with a follow-up prompt (as_ followed by 16 hex characters)." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "window_source": { "type": "string", "description": "Where this turn's as_of and from came from: request (this request sent at least one), session (a follow-up that sent neither, so the session's own were kept) or default (a first prompt that sent neither: the latest date in the release, with no from)." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities you asked about that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the answer. Present only when not empty." } }, "additionalProperties": true }, "example": { "as_of": "2026-09-26", "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "graph": { "count": 5, "edges": [ { "first_seen": "2024-08-30", "last_seen": "2026-09-21", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "invests_in", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 161 }, { "first_seen": "2024-08-29", "last_seen": "2026-09-21", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "planned_investment_in", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 144 }, { "first_seen": "2023-10-08", "last_seen": "2026-09-22", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "collaborates_with", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 125 }, { "first_seen": "2023-10-06", "last_seen": "2026-09-23", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "business_partner_of", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 104 }, { "first_seen": "2024-08-30", "last_seen": "2026-09-21", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "funds", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 90 } ], "nodes": [ { "focus": true, "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, { "focus": true, "name": "OpenAI", "normalized": "openai", "type": "ORG" } ], "total": 5, "truncated": false }, "id": "ap_c8171de7e5d85481", "message": "As of September 26, 2026, Nvidia and OpenAI are connected through five direct relationships, all one step apart:\n\n1. **Nvidia invests in OpenAI** — evidence from August 30, 2024 to September 21, 2026 (backed by 161 events)\n2. **Nvidia planned investment in OpenAI** — August 29, 2024 to September 21, 2026 (144 events)\n3. **Nvidia collaborates with OpenAI** — October 8, 2023 to September 22, 2026 (125 events)\n4. **Nvidia is a business partner of OpenAI** — October 6, 2023 to September 23, 2026 (104 events)\n5. **Nvidia funds OpenAI** — August 30, 2024 to September 21, 2026 (90 events)\n\nIn short, the graph shows a close, multi-faceted tie: Nvidia appears as an investor and funder of OpenAI, with a planned investment also recorded, alongside an ongoing collaboration and business partnership. All five connections are direct, so no multi-step paths were needed.", "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_prompt_v1", "session": "as_78bfc64a7f2a00fb", "took_ms": 3632, "window_source": "default" } }, "application/x-ndjson": { "schema": { "type": "string" }, "x-description": "With stream=true, the response is a newline-delimited JSON stream; each line is a separate JSON message." } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.\n\nunknown_session: No session with this id exists for your API key: it was never issued, or it belongs to another key. Omit session to start a new conversation.", "x-nosible-error-codes": [ "unknown_entity", "not_found", "unknown_session" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "session_busy: The session's previous prompt is still running: of two follow-ups sent at once on one session, one runs and the other gets this. Wait, then send it again.", "x-nosible-error-codes": [ "session_busy" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.\n\nsession_expired: Your own session was started on a graph release that has since been replaced; start a new conversation without session.", "x-nosible-error-codes": [ "cursor_expired", "session_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.\n\nupstream_error: The language model failed; retry.", "x-nosible-error-codes": [ "backend_error", "upstream_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.\n\nupstream_timeout: The language model did not answer in time; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout", "upstream_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The question, up to 8,000 characters.", "example": "How is Nvidia connected to OpenAI?" }, "session": { "type": "string", "description": "Session id from a previous response. Continues the conversation and the graph on screen. A session belongs to the API key that created it: another key gets 404 unknown_session. Two follow-ups sent at once on one session cannot both run: one gets 409 session_busy.", "example": "as_3565eeb24b3721a2" }, "limit": { "type": "integer", "description": "Maximum relationships drawn. Defaults to 300, maximum 1,000.", "example": 10 }, "stream": { "type": "boolean", "description": "When true the response is NDJSON: activity lines while the graph is built, then one reply line.", "example": false }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. In a follow-up (session) it defaults to the session's own as_of; a date you send replaces only itself, for this turn and the later ones. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). In a follow-up (session) it defaults to the session's own from; a date you send replaces only itself, for this turn and the later ones. A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "prompt" ] }, "examples": { "atlas_prompt": { "summary": "By prompt", "value": { "prompt": "How is Nvidia connected to OpenAI?" } } } } } } } }, "/api/v2.0/atlas/graphs/entities": { "post": { "operationId": "atlas_entities", "summary": "By entity", "description": "Get the neighbourhood around one or more entities, out to a chosen number of hops, or the entities they share.\n\nUse By entity to fetch the graph around companies, people, places or products as of a date. The example asks who supplied Nvidia as of the end of 2024: every count and date comes only from events on or before as_of, graph.total counts every supplier relationship that matched, and limit keeps the strongest.", "tags": [ "BUILD GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-entities" }, "x-nosible-reference-pages": [ "atlas-entities" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "entities": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The entities you asked about, as resolved." }, "graph": { "type": "object", "properties": { "count": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "object": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "predicate": { "type": "string" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "number" } }, "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "focus": { "type": "boolean" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "integer", "description": "Every relationship that matches the request before limit, however many there are: the true count, not the number the walk reached. Only with hops above 1 around a very large entity, where the walk stops at 20,000 relationships, is it the number reached (see total_capped)." }, "total_capped": { "type": "boolean", "description": "false when graph.total is exact. true only with hops above 1 around a very large entity, when the walk stopped at its 20,000-relationship budget: total is then a lower bound and the graph has more relationships than it counts." }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, count, total, truncated, total_capped}. nodes carry focus: true for the entities you asked about; edges are relationships, strongest first; count is the edges returned and total counts every matching relationship before the limit, however many there are. truncated is true when the limit dropped edges. total_capped is true only for hops above 1 around a very large entity: the walk stops at 20,000 relationships, total is then what it reached (a lower bound) and the graph has more." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities you asked about that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the answer. Present only when not empty." } }, "additionalProperties": true }, "example": { "as_of": "2024-12-31", "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2024-12-31" }, "entities": [ { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" } ], "graph": { "count": 4, "edges": [ { "first_seen": "2014-08-26", "last_seen": "2024-12-28", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "TSMC", "normalized": "tsmc", "type": "ORG" }, "support": 75 }, { "first_seen": "2022-06-09", "last_seen": "2024-11-05", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "SK Hynix", "normalized": "sk hynix", "type": "ORG" }, "support": 29 }, { "first_seen": "2015-02-03", "last_seen": "2024-12-26", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "Samsung", "normalized": "samsung", "type": "ORG" }, "support": 21 }, { "first_seen": "2016-03-24", "last_seen": "2024-07-09", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "Micron", "normalized": "micron", "type": "ORG" }, "support": 14 } ], "nodes": [ { "focus": true, "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, { "focus": false, "name": "TSMC", "normalized": "tsmc", "type": "ORG" }, { "focus": false, "name": "SK Hynix", "normalized": "sk hynix", "type": "ORG" }, { "focus": false, "name": "Samsung", "normalized": "samsung", "type": "ORG" }, { "focus": false, "name": "Micron", "normalized": "micron", "type": "ORG" } ], "total": 40, "total_capped": false, "truncated": true }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_graph_v1", "took_ms": 10 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "1 to 10 entities. An entity as {type, name}: type is ORG, PERSON, GPE, LOC or PRODUCT; name is matched case-insensitively, and an alias (\"NVIDIA\", \"Trump\") resolves to the entity it names. Names are World V2.0's canonical names; for a ticker, send its company as an ORG.", "example": [ { "type": "ORG", "name": "Nvidia" } ] }, "hops": { "type": "integer", "description": "How far to expand, 1 to 3. Defaults to 1. Countries and places are shown but not expanded unless you asked about a place.", "example": 1 }, "combine": { "type": "string", "description": "union (default) or intersect. intersect needs at least two entities and hops 1, and returns the entities they all share.", "example": "union" }, "limit": { "type": "integer", "description": "Maximum relationships returned. Defaults to 300, maximum 1,000. Relationships touching your entities come first.", "example": 4 }, "direction": { "type": "string", "description": "in (the entity is the object), out (the entity is the subject) or both. Defaults to both.", "example": "in" }, "predicates": { "type": "array", "items": { "type": "string" }, "description": "Keep only these relationship types (array of strings). List them with Relationship types.", "example": [ "supplier_to" ] }, "exclude_predicates": { "type": "array", "items": { "type": "string" }, "description": "Drop these relationship types (array of strings).", "example": [ "located_in" ] }, "other_types": { "type": "array", "items": { "type": "string" }, "description": "Keep only relationships whose other end has one of these entity types.", "example": [ "ORG" ] }, "exclude_types": { "type": "array", "items": { "type": "string" }, "description": "Drop relationships where either end has one of these entity types.", "example": [ "GPE", "LOC" ] }, "min_support": { "type": "integer", "description": "Minimum number of distinct supporting events inside the window: a whole number of 1 or more, with no upper cap. Defaults to 1.", "example": 5 }, "aliases": { "type": "string", "description": "hide (default), include or only. Alias relationships are normalized_to (spelling variants) and alias_of (short names).", "example": "hide" }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "entities" ] }, "examples": { "atlas_entities": { "summary": "By entity", "value": { "entities": [ { "type": "ORG", "name": "Nvidia" } ], "hops": 1, "direction": "in", "predicates": [ "supplier_to" ], "limit": 4, "as_of": "2024-12-31" } } } } } } } }, "/api/v2.0/atlas/graphs/paths": { "post": { "operationId": "atlas_paths", "summary": "By path", "description": "Find how two entities are connected, strongest connections first.\n\nUse By path to explain a link between two entities. Paths are ranked by their weakest relationship: a path is only as strong as its least-supported step, so a path through a hub such as a country ranks low when one of its steps rests on one or two events. Ties go to fewer hops, then to higher total support. Atlas finds every path of the shortest length, and longer ones until it has 25, and ranks them all; truncated is true only when a work budget stopped the search before the shortest paths were all found or before max_paths were found, in which case longer paths may exist that were not returned. Set time_respecting to require that each link was reported after the one before it. The example finds how Nvidia reaches Sam Altman over relationships with at least 10 supporting events: through OpenAI, which Nvidia invests in and where Sam Altman holds a position. Each relationship is a step of its own, so two relationship types between the same entities make two paths; each chain of entities appears once, with its strongest relationship types, before any chain appears again.", "tags": [ "BUILD GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-paths" }, "x-nosible-reference-pages": [ "atlas-paths" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "graph": { "type": "object", "properties": { "count": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "object": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "predicate": { "type": "string" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "number" } }, "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "focus": { "type": "boolean" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, count, total, truncated}. nodes carry focus: true for the entities you asked about; edges are relationships, strongest first; total counts edges before the limit." }, "paths": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{length, steps: [{relationship, from, to, evidence_date}]}], strongest first: by the support of each path's weakest relationship, then fewer hops, then total support. Each chain of entities appears once before any chain appears again." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "truncated": { "type": "boolean", "description": "True when a work budget stopped the search." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities you asked about that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the answer. Present only when not empty." } }, "additionalProperties": true }, "example": { "as_of": "2026-09-26", "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "graph": { "count": 4, "edges": [ { "first_seen": "2018-02-22", "last_seen": "2026-09-26", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "holds_position_at", "subject": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" }, "support": 2023 }, { "first_seen": "2024-08-30", "last_seen": "2026-09-21", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "invests_in", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 161 }, { "first_seen": "2011-01-05", "last_seen": "2026-07-28", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "business_partner_of", "subject": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "support": 126 }, { "first_seen": "2023-11-20", "last_seen": "2023-11-30", "object": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "predicate": "hired_by", "subject": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" }, "support": 28 } ], "nodes": [ { "focus": true, "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, { "focus": true, "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" }, { "focus": false, "name": "OpenAI", "normalized": "openai", "type": "ORG" }, { "focus": false, "name": "Microsoft", "normalized": "microsoft", "type": "ORG" } ], "total": 4, "truncated": false }, "paths": [ { "length": 2, "steps": [ { "evidence_date": null, "from": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "relationship": { "first_seen": "2024-08-30", "last_seen": "2026-09-21", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "invests_in", "subject": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "support": 161 }, "to": { "name": "OpenAI", "normalized": "openai", "type": "ORG" } }, { "evidence_date": null, "from": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "relationship": { "first_seen": "2018-02-22", "last_seen": "2026-09-26", "object": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "predicate": "holds_position_at", "subject": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" }, "support": 2023 }, "to": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" } } ] }, { "length": 2, "steps": [ { "evidence_date": null, "from": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "relationship": { "first_seen": "2011-01-05", "last_seen": "2026-07-28", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "business_partner_of", "subject": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "support": 126 }, "to": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" } }, { "evidence_date": null, "from": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "relationship": { "first_seen": "2023-11-20", "last_seen": "2023-11-30", "object": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "predicate": "hired_by", "subject": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" }, "support": 28 }, "to": { "name": "Sam Altman", "normalized": "sam altman", "type": "PERSON" } } ] } ], "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_paths_v1", "took_ms": 3, "truncated": false } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "additionalProperties": true, "description": "An entity as {type, name}: type is ORG, PERSON, GPE, LOC or PRODUCT; name is matched case-insensitively, and an alias (\"NVIDIA\", \"Trump\") resolves to the entity it names. Names are World V2.0's canonical names; for a ticker, send its company as an ORG.", "example": { "type": "ORG", "name": "Nvidia" } }, "target": { "type": "object", "additionalProperties": true, "description": "An entity as {type, name}: type is ORG, PERSON, GPE, LOC or PRODUCT; name is matched case-insensitively, and an alias (\"NVIDIA\", \"Trump\") resolves to the entity it names. Names are World V2.0's canonical names; for a ticker, send its company as an ORG.", "example": { "type": "PERSON", "name": "Sam Altman" } }, "max_hops": { "type": "integer", "description": "Longest path considered, 1 to 6. Defaults to 4.", "example": 3 }, "max_paths": { "type": "integer", "description": "Paths returned, 1 to 25. Defaults to 5.", "example": 2 }, "time_respecting": { "type": "boolean", "description": "When true, each step's evidence is dated on or after the previous step's, and every step reports evidence_date.", "example": false }, "direction": { "type": "string", "description": "in (the entity is the object), out (the entity is the subject) or both. Defaults to both.", "example": "both" }, "predicates": { "type": "array", "items": { "type": "string" }, "description": "Keep only these relationship types (array of strings). List them with Relationship types.", "example": [ "supplier_to" ] }, "exclude_predicates": { "type": "array", "items": { "type": "string" }, "description": "Drop these relationship types (array of strings).", "example": [ "located_in" ] }, "other_types": { "type": "array", "items": { "type": "string" }, "description": "Keep only relationships whose other end has one of these entity types.", "example": [ "ORG" ] }, "exclude_types": { "type": "array", "items": { "type": "string" }, "description": "Drop relationships where either end has one of these entity types.", "example": [ "GPE", "LOC" ] }, "min_support": { "type": "integer", "description": "Minimum number of distinct supporting events inside the window: a whole number of 1 or more, with no upper cap. Defaults to 1.", "example": 10 }, "aliases": { "type": "string", "description": "hide (default), include or only. Alias relationships are normalized_to (spelling variants) and alias_of (short names).", "example": "hide" }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "source", "target" ] }, "examples": { "atlas_paths": { "summary": "By path", "value": { "source": { "type": "ORG", "name": "Nvidia" }, "target": { "type": "PERSON", "name": "Sam Altman" }, "max_hops": 3, "max_paths": 2, "min_support": 10 } } } } } } } }, "/api/v2.0/atlas/graphs/ownership": { "post": { "operationId": "atlas_ownership", "summary": "By ownership", "description": "Trace who ultimately owns an entity, or what it owns.\n\nUse By ownership to walk an ownership chain. Each link needs at least 10 supporting events unless you send another min_support: links reported only once or twice are mostly extraction errors, and at min_support 1 a company can collect hundreds of unrelated \"ultimate owners\". With the default predicates the chain also climbs through shareholders; pass the three control predicates to follow control only, as in the example: YouTube's chain climbs through Google to Alphabet, its ultimate owner.", "tags": [ "BUILD GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-ownership" }, "x-nosible-reference-pages": [ "atlas-ownership" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "cycle_cut": { "type": "boolean", "description": "True when an ownership cycle was found and cut." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "entity": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true, "description": "The entity you asked about." }, "graph": { "type": "object", "properties": { "count": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "object": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "predicate": { "type": "string" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "number" } }, "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "focus": { "type": "boolean" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, count, total, truncated}. nodes carry focus: true for the entities you asked about; edges are relationships, strongest first; total counts edges before the limit." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "truncated": { "type": "boolean", "description": "True when a work budget cut the chain short." }, "ultimate_owners": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Entities in the chain with no owner of their own inside the window. Empty for direction down." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities you asked about that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the answer. Present only when not empty." } }, "additionalProperties": true }, "example": { "as_of": "2026-09-26", "cycle_cut": false, "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "entity": { "name": "YouTube", "normalized": "youtube", "type": "ORG" }, "graph": { "count": 15, "edges": [ { "first_seen": "2015-08-11", "last_seen": "2026-09-25", "object": { "name": "Alphabet", "normalized": "alphabet", "type": "ORG" }, "predicate": "subsidiary_of", "subject": { "name": "Google", "normalized": "google", "type": "ORG" }, "support": 1407 }, { "first_seen": "2015-08-13", "last_seen": "2026-09-25", "object": { "name": "Google", "normalized": "google", "type": "ORG" }, "predicate": "has_controlling_interest_in", "subject": { "name": "Alphabet", "normalized": "alphabet", "type": "ORG" }, "support": 821 }, { "first_seen": "2015-08-10", "last_seen": "2026-09-21", "object": { "name": "Google", "normalized": "google", "type": "ORG" }, "predicate": "has_controlling_interest_in", "subject": { "name": "Alphabet", "normalized": "alphabet", "type": "ORG" }, "support": 636 }, { "first_seen": "2010-01-20", "last_seen": "2026-09-10", "object": { "name": "YouTube", "normalized": "youtube", "type": "ORG" }, "predicate": "has_controlling_interest_in", "subject": { "name": "Google", "normalized": "google", "type": "ORG" }, "support": 617 }, { "first_seen": "2010-01-20", "last_seen": "2026-09-10", "object": { "name": "Google", "normalized": "google", "type": "ORG" }, "predicate": "subsidiary_of", "subject": { "name": "YouTube", "normalized": "youtube", "type": "ORG" }, "support": 602 }, { "first_seen": "2015-08-10", "last_seen": "2026-09-24", "object": { "name": "Alphabet", "normalized": "alphabet", "type": "ORG" }, "predicate": "subsidiary_of", "subject": { "name": "Google", "normalized": "google", "type": "ORG" }, "support": 563 } ], "nodes": [ { "focus": true, "name": "YouTube", "normalized": "youtube", "type": "ORG" }, { "focus": false, "name": "Google", "normalized": "google", "type": "ORG" }, { "focus": false, "name": "Alphabet", "normalized": "alphabet", "type": "ORG" }, { "focus": false, "name": "Google", "normalized": "google", "type": "ORG" } ], "total": 15, "truncated": false }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_ownership_v1", "took_ms": 2, "truncated": false, "ultimate_owners": [ { "name": "Alphabet", "normalized": "alphabet", "type": "ORG" } ] } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "object", "additionalProperties": true, "description": "An entity as {type, name}: type is ORG, PERSON, GPE, LOC or PRODUCT; name is matched case-insensitively, and an alias (\"NVIDIA\", \"Trump\") resolves to the entity it names. Names are World V2.0's canonical names; for a ticker, send its company as an ORG.", "example": { "type": "ORG", "name": "YouTube" } }, "direction": { "type": "string", "description": "up (default) to the owners, down to what it owns, or both.", "example": "up" }, "predicates": { "type": "array", "items": { "type": "string" }, "description": "Ownership relationship types followed. Defaults to subsidiary_of, division_of, has_controlling_interest_in and owns_equity_stake_in. Leave out owns_equity_stake_in to follow control only.", "example": [ "subsidiary_of", "division_of", "has_controlling_interest_in" ] }, "min_support": { "type": "integer", "description": "Minimum supporting events per ownership link: a whole number of 1 or more, with no upper cap. Defaults to 10, because ownership links reported only a few times are mostly extraction errors that add false owners up the chain. Send 1 to see every link.", "example": 20 }, "max_depth": { "type": "integer", "description": "Levels followed, 1 to 10. Defaults to 6.", "example": 6 }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "entity" ] }, "examples": { "atlas_ownership": { "summary": "By ownership", "value": { "entity": { "type": "ORG", "name": "YouTube" }, "predicates": [ "subsidiary_of", "division_of", "has_controlling_interest_in" ], "min_support": 20 } } } } } } } }, "/api/v2.0/atlas/analysis/rankings": { "post": { "operationId": "atlas_rankings", "summary": "Rank entities", "description": "Rank the most important entities in a graph (personalised PageRank).\n\nUse Rank entities to find what matters most around your entities, from the point of view of the seeds. Scores are personalised PageRank (damping 0.85) over relationships weighted by support; identical requests give identical answers. A seed need not be one of the entities the graph is built from, only in the graph: the example ranks the graph around four chipmakers for OpenAI, so the chipmakers closest to OpenAI, Nvidia and AMD, rank above Intel and TSMC.", "tags": [ "ANALYSE GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-rankings" }, "x-nosible-reference-pages": [ "atlas-rankings" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approximate": { "type": "boolean", "description": "True when the answer comes from sampling or an iteration cap." }, "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "ranking": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{rank, entity, score}], highest score first." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "scope": { "type": "object", "properties": { "edges": { "type": "number" }, "nodes": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, truncated}: the size of the graph analysed." }, "seeds_outside_graph": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Seeds the graph does not contain, so they could not personalise the ranking. When none of the seeds is in the graph, the ranking is personalised to the graph's entities instead." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities in graph (or, for Rank entities, in seeds) that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the analysis: never ranked, grouped or scored. When none of graph's entities existed, the answer is empty with a scope of 0 nodes. Present only when not empty." } }, "additionalProperties": true }, "example": { "approximate": false, "as_of": "2026-09-26", "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "ranking": [ { "entity": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "rank": 1, "score": 0.2531475565243649 }, { "entity": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "rank": 2, "score": 0.15426975557315697 }, { "entity": { "name": "AMD", "normalized": "amd", "type": "ORG" }, "rank": 3, "score": 0.1275797457058895 }, { "entity": { "name": "Intel", "normalized": "intel", "type": "ORG" }, "rank": 4, "score": 0.05315856805503702 }, { "entity": { "name": "TSMC", "normalized": "tsmc", "type": "ORG" }, "rank": 5, "score": 0.03290359510517457 } ], "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_rankings_v1", "scope": { "edges": 4859, "nodes": 1181, "truncated": false }, "seeds_outside_graph": [], "took_ms": 130 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "additionalProperties": true, "description": "The graph to analyse: the same object as the By entity body (entities, hops 1 to 3 defaulting to 2, and the filters). as_of and from go at the top level, not inside graph. Scope is capped at 100,000 entities.", "example": { "entities": [ { "type": "ORG", "name": "Nvidia" }, { "type": "ORG", "name": "AMD" }, { "type": "ORG", "name": "Intel" }, { "type": "ORG", "name": "TSMC" } ], "hops": 1, "exclude_types": [ "GPE", "LOC" ], "min_support": 5 } }, "seeds": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Entities the ranking is personalised to, up to 100. Defaults to the graph's entities.", "example": [ { "type": "ORG", "name": "OpenAI" } ] }, "limit": { "type": "integer", "description": "Entities returned. Defaults to 25, maximum 500.", "example": 5 }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "graph" ] }, "examples": { "atlas_rankings": { "summary": "Rank entities", "value": { "graph": { "entities": [ { "type": "ORG", "name": "Nvidia" }, { "type": "ORG", "name": "AMD" }, { "type": "ORG", "name": "Intel" }, { "type": "ORG", "name": "TSMC" } ], "hops": 1, "exclude_types": [ "GPE", "LOC" ], "min_support": 5 }, "seeds": [ { "type": "ORG", "name": "OpenAI" } ], "limit": 5 } } } } } } } }, "/api/v2.0/atlas/analysis/communities": { "post": { "operationId": "atlas_communities", "summary": "Find communities", "description": "Find clusters of closely linked entities.\n\nUse Find communities to split a graph into groups that are more connected inside than out (Louvain). top_predicates says what holds each group together. A graph around a single entity is one star, so start from two or more entities. The example splits the graph around Nvidia, AMD, Intel and TSMC; each of its three largest communities forms around one of the chipmakers, with its people and partners.", "tags": [ "ANALYSE GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-communities" }, "x-nosible-reference-pages": [ "atlas-communities" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approximate": { "type": "boolean", "description": "Always true: community detection (Louvain) finds a good division, not a provably best one. The same request always returns the same communities." }, "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "communities": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{id, size, relationships, members, top_predicates}], largest first." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "modularity": { "type": "number", "description": "How well the graph divides at the requested resolution. At resolution 1 it is the classic modularity, from 0 (no structure) towards 1; values at different resolutions are not comparable." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "scope": { "type": "object", "properties": { "edges": { "type": "number" }, "nodes": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, truncated}: the size of the graph analysed." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities in graph (or, for Rank entities, in seeds) that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the analysis: never ranked, grouped or scored. When none of graph's entities existed, the answer is empty with a scope of 0 nodes. Present only when not empty." } }, "additionalProperties": true }, "example": { "approximate": true, "as_of": "2026-09-26", "communities": [ { "id": 1, "members": [ { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, { "name": "Arm", "normalized": "arm", "type": "ORG" }, { "name": "Jensen Huang", "normalized": "jensen huang", "type": "PERSON" } ], "relationships": 1906, "size": 496, "top_predicates": [ { "count": 182, "predicate": "produces_product" }, { "count": 161, "predicate": "develops_product" }, { "count": 154, "predicate": "brand_of" }, { "count": 149, "predicate": "collaborates_with" }, { "count": 141, "predicate": "business_partner_of" } ] }, { "id": 2, "members": [ { "name": "Intel", "normalized": "intel", "type": "ORG" }, { "name": "Altera", "normalized": "altera", "type": "ORG" }, { "name": "Mobileye", "normalized": "mobileye", "type": "ORG" }, { "name": "Pat Gelsinger", "normalized": "pat gelsinger", "type": "PERSON" } ], "relationships": 1234, "size": 351, "top_predicates": [ { "count": 137, "predicate": "produces_product" }, { "count": 129, "predicate": "develops_product" }, { "count": 111, "predicate": "announced_product" }, { "count": 97, "predicate": "launched_product" }, { "count": 92, "predicate": "brand_of" } ] }, { "id": 3, "members": [ { "name": "AMD", "normalized": "amd", "type": "ORG" }, { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, { "name": "Samsung", "normalized": "samsung", "type": "ORG" }, { "name": "Samsung Electronics", "normalized": "samsung electronics", "type": "ORG" } ], "relationships": 971, "size": 267, "top_predicates": [ { "count": 151, "predicate": "produces_product" }, { "count": 114, "predicate": "develops_product" }, { "count": 100, "predicate": "brand_of" }, { "count": 95, "predicate": "announced_product" }, { "count": 83, "predicate": "launched_product" } ] } ], "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "modularity": 0.5498172052940153, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_communities_v1", "scope": { "edges": 4859, "nodes": 1181, "truncated": false }, "took_ms": 3 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "additionalProperties": true, "description": "The graph to analyse: the same object as the By entity body (entities, hops 1 to 3 defaulting to 2, and the filters). as_of and from go at the top level, not inside graph. Scope is capped at 100,000 entities.", "example": { "entities": [ { "type": "ORG", "name": "Nvidia" }, { "type": "ORG", "name": "AMD" }, { "type": "ORG", "name": "Intel" }, { "type": "ORG", "name": "TSMC" } ], "hops": 1, "exclude_types": [ "GPE", "LOC" ], "min_support": 5 } }, "resolution": { "type": "number", "description": "Above 1 gives more, smaller communities; below 1 fewer, larger ones. Defaults to 1.0.", "example": 1 }, "limit": { "type": "integer", "description": "Communities returned, largest first. Defaults to 20, maximum 100.", "example": 3 }, "members": { "type": "integer", "description": "Members listed per community. Defaults to 10, maximum 50.", "example": 4 }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "graph" ] }, "examples": { "atlas_communities": { "summary": "Find communities", "value": { "graph": { "entities": [ { "type": "ORG", "name": "Nvidia" }, { "type": "ORG", "name": "AMD" }, { "type": "ORG", "name": "Intel" }, { "type": "ORG", "name": "TSMC" } ], "hops": 1, "exclude_types": [ "GPE", "LOC" ], "min_support": 5 }, "limit": 3, "members": 4 } } } } } } } }, "/api/v2.0/atlas/analysis/bridges": { "post": { "operationId": "atlas_bridges", "summary": "Find bridges", "description": "Find the entities that connect otherwise separate groups (betweenness centrality).\n\nUse Find bridges to find the entities that sit on the paths between groups, such as the intermediaries between two companies' networks. Scores are betweenness centrality, sampled with a fixed seed when the graph has more entities than samples (approximate is then true). Around one entity at one hop the graph is a star in which only the centre scores, so start from entities that are not directly connected: the example asks which investors connect OpenAI, Anthropic and xAI. The three labs, each the hub of its own investors, rank first; next come Sequoia Capital and Nvidia, which invest in all three, ahead of investors in two of them.", "tags": [ "ANALYSE GRAPHS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-bridges" }, "x-nosible-reference-pages": [ "atlas-bridges" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approximate": { "type": "boolean", "description": "True when the answer comes from sampling or an iteration cap." }, "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "bridges": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{rank, entity, score}], highest score first." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "samples": { "type": "integer", "description": "Source entities sampled." }, "schema": { "type": "string", "description": "Response schema name." }, "scope": { "type": "object", "properties": { "edges": { "type": "number" }, "nodes": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "{nodes, edges, truncated}: the size of the graph analysed." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "absent_entities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT." }, "name": { "type": "string", "description": "The entity's canonical name: an alias you sent resolves to it." }, "normalized": { "type": "string", "description": "The entity's normalized spelling." }, "reason": { "type": "string", "description": "Why the entity is absent: no relationship or event on or before as_of, so it does not exist in the graph at that point in time. To see it, send an as_of after its first event (Entity relationships gives an entity's first_seen)." } } }, "description": "Entities in graph (or, for Rank entities, in seeds) that had no event on or before as_of: {type, name, normalized, reason}. They did not exist in the graph at that date, so they are left out of the analysis: never ranked, grouped or scored. When none of graph's entities existed, the answer is empty with a scope of 0 nodes. Present only when not empty." } }, "additionalProperties": true }, "example": { "approximate": false, "as_of": "2026-09-26", "bridges": [ { "entity": { "name": "Anthropic", "normalized": "anthropic", "type": "ORG" }, "rank": 1, "score": 0.629208155523945 }, { "entity": { "name": "OpenAI", "normalized": "openai", "type": "ORG" }, "rank": 2, "score": 0.5026078710289238 }, { "entity": { "name": "xAI", "normalized": "xai", "type": "ORG" }, "rank": 3, "score": 0.2636320531057373 }, { "entity": { "name": "Sequoia Capital", "normalized": "sequoia capital", "type": "ORG" }, "rank": 4, "score": 0.1429587482219061 }, { "entity": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "rank": 5, "score": 0.1429587482219061 }, { "entity": { "name": "Microsoft", "normalized": "microsoft", "type": "ORG" }, "rank": 6, "score": 0.04089615931721195 } ], "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "samples": 39, "schema": "nosible_atlas_bridges_v1", "scope": { "edges": 46, "nodes": 39, "truncated": false }, "took_ms": 8 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "additionalProperties": true, "description": "The graph to analyse: the same object as the By entity body (entities, hops 1 to 3 defaulting to 2, and the filters). as_of and from go at the top level, not inside graph. Scope is capped at 100,000 entities.", "example": { "entities": [ { "type": "ORG", "name": "OpenAI" }, { "type": "ORG", "name": "Anthropic" }, { "type": "ORG", "name": "xAI" } ], "hops": 1, "direction": "in", "predicates": [ "invests_in" ], "min_support": 5 } }, "limit": { "type": "integer", "description": "Entities returned. Defaults to 25, maximum 500.", "example": 6 }, "samples": { "type": "integer", "description": "Source entities sampled. Defaults to 256, maximum 2,048. More samples are slower and more precise.", "example": 256 }, "as_of": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" }, "from": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } }, "additionalProperties": true, "required": [ "graph" ] }, "examples": { "atlas_bridges": { "summary": "Find bridges", "value": { "graph": { "entities": [ { "type": "ORG", "name": "OpenAI" }, { "type": "ORG", "name": "Anthropic" }, { "type": "ORG", "name": "xAI" } ], "hops": 1, "direction": "in", "predicates": [ "invests_in" ], "min_support": 5 }, "limit": 6 } } } } } } } }, "/api/v2.0/atlas/entities/relationships": { "get": { "operationId": "atlas_entity_relationships", "summary": "Entity relationships", "description": "List an entity's relationships, strongest first.\n\nUse Entity relationships to page through everything known about one entity at a point in time, strongest first (support, then most recent). The example lists Nvidia's suppliers as of the end of 2024. Pages are stable: the same request and cursor return the same page.", "tags": [ "GET DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-entity-relationships" }, "x-nosible-reference-pages": [ "atlas-entity-relationships" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. For a ticker, send its company as an ORG.", "schema": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. For a ticker, send its company as an ORG.", "example": "ORG" } }, { "name": "name", "in": "query", "required": true, "description": "Entity name, matched case-insensitively. An alias resolves to the entity it names.", "schema": { "type": "string", "description": "Entity name, matched case-insensitively. An alias resolves to the entity it names.", "example": "Nvidia" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, maximum 500.", "schema": { "type": "integer", "description": "Page size. Defaults to 50, maximum 500.", "example": 4 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "description": "next_cursor from the previous page." } }, { "name": "direction", "in": "query", "required": false, "description": "in (the entity is the object), out (the entity is the subject) or both. Defaults to both.", "schema": { "type": "string", "description": "in (the entity is the object), out (the entity is the subject) or both. Defaults to both.", "example": "in" } }, { "name": "predicates", "in": "query", "required": false, "description": "Keep only these relationship types (comma-separated string). List them with Relationship types.", "schema": { "type": "string", "description": "Keep only these relationship types (comma-separated string). List them with Relationship types.", "example": "supplier_to" } }, { "name": "exclude_predicates", "in": "query", "required": false, "description": "Drop these relationship types (comma-separated string).", "schema": { "type": "string", "description": "Drop these relationship types (comma-separated string).", "example": "located_in" } }, { "name": "other_types", "in": "query", "required": false, "description": "Keep only relationships whose other end has one of these entity types.", "schema": { "type": "string", "description": "Keep only relationships whose other end has one of these entity types.", "example": "ORG" } }, { "name": "exclude_types", "in": "query", "required": false, "description": "Drop relationships where either end has one of these entity types.", "schema": { "type": "string", "description": "Drop relationships where either end has one of these entity types.", "example": "GPE,LOC" } }, { "name": "min_support", "in": "query", "required": false, "description": "Minimum number of distinct supporting events inside the window: a whole number of 1 or more, with no upper cap. Defaults to 1.", "schema": { "type": "integer", "description": "Minimum number of distinct supporting events inside the window: a whole number of 1 or more, with no upper cap. Defaults to 1.", "example": 5 } }, { "name": "aliases", "in": "query", "required": false, "description": "hide (default), include or only. Alias relationships are normalized_to (spelling variants) and alias_of (short names).", "schema": { "type": "string", "description": "hide (default), include or only. Alias relationships are normalized_to (spelling variants) and alias_of (short names).", "example": "hide" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "schema": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" } }, { "name": "from", "in": "query", "required": false, "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "schema": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "count": { "type": "integer", "description": "Relationships in this page." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "entity": { "type": "object", "properties": { "events": { "type": "number" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "relationships": { "type": "number" }, "type": { "type": "string" } }, "additionalProperties": true, "description": "The entity with its events, relationships, first_seen and last_seen inside the window." }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page, null on the last." }, "order": { "type": "string", "description": "Always support_desc." }, "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Relationships in this page: {subject, predicate, object, support, first_seen, last_seen}." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "total": { "type": "integer", "description": "Relationships matching the filters." } }, "additionalProperties": true }, "example": { "as_of": "2024-12-31", "count": 4, "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2024-12-31" }, "entity": { "events": 6904, "first_seen": "2010-01-07", "last_seen": "2024-12-31", "name": "Nvidia", "normalized": "nvidia", "relationships": 9483, "type": "ORG" }, "next_cursor": "djMKMDU2NmUyMjFkNmZjZWUzMGQzNmE0ZDEzYzNkOTUzZTUKZW50aXR5X3JlbGF0aW9uc2hpcHMKMzg3YjBjZGQyMzdhZjE1MgoxNDoyMDI0MDcwOTozMTUxNDc1OjM1MTo2NDI1ODI3CjJlNGJmM2U4MWJkMzZiYmI", "order": "support_desc", "relationships": [ { "first_seen": "2014-08-26", "last_seen": "2024-12-28", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "TSMC", "normalized": "tsmc", "type": "ORG" }, "support": 75 }, { "first_seen": "2022-06-09", "last_seen": "2024-11-05", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "SK Hynix", "normalized": "sk hynix", "type": "ORG" }, "support": 29 }, { "first_seen": "2015-02-03", "last_seen": "2024-12-26", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "Samsung", "normalized": "samsung", "type": "ORG" }, "support": 21 }, { "first_seen": "2016-03-24", "last_seen": "2024-07-09", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "Micron", "normalized": "micron", "type": "ORG" }, "support": 14 } ], "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_entity_relationships_v1", "took_ms": 8, "total": 40 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v2.0/atlas/entities/similar": { "get": { "operationId": "atlas_similar", "summary": "Similar entities", "description": "Find entities with similar connections.\n\nUse Similar entities to find peers: entities connected to the same things. score is the Jaccard overlap of neighbour sets. When approximate is false the list is provably the exact top limit; bound is the highest score anything not examined could have.", "tags": [ "GET DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-similar" }, "x-nosible-reference-pages": [ "atlas-similar" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. For a ticker, send its company as an ORG.", "schema": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. For a ticker, send its company as an ORG.", "example": "ORG" } }, { "name": "name", "in": "query", "required": true, "description": "Entity name, matched case-insensitively.", "schema": { "type": "string", "description": "Entity name, matched case-insensitively.", "example": "Nvidia" } }, { "name": "predicates", "in": "query", "required": false, "description": "Compare only these relationship types (comma-separated).", "schema": { "type": "string", "description": "Compare only these relationship types (comma-separated).", "example": "supplier_to" } }, { "name": "direction", "in": "query", "required": false, "description": "in, out or both (default).", "schema": { "type": "string", "description": "in, out or both (default).", "example": "both" } }, { "name": "min_shared", "in": "query", "required": false, "description": "Minimum neighbours in common: a whole number of 1 or more, with no upper cap. Defaults to 2.", "schema": { "type": "integer", "description": "Minimum neighbours in common: a whole number of 1 or more, with no upper cap. Defaults to 2.", "example": 2 } }, { "name": "limit", "in": "query", "required": false, "description": "Entities returned. Defaults to 25, maximum 100.", "schema": { "type": "integer", "description": "Entities returned. Defaults to 25, maximum 100.", "example": 3 } }, { "name": "as_of", "in": "query", "required": false, "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "schema": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" } }, { "name": "from", "in": "query", "required": false, "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "schema": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approximate": { "type": "boolean", "description": "False when the returned list is provably the exact top limit." }, "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "bound": { "type": "number", "description": "Highest score an entity not examined could have." }, "coverage": { "type": "object", "properties": { "candidates": { "type": "number" }, "candidates_examined": { "type": "number" }, "neighbours": { "type": "number" }, "scanned": { "type": "number" } }, "additionalProperties": true, "description": "{neighbours, scanned, candidates, candidates_examined}: how much of the graph was searched." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "entity": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true, "description": "The entity you asked about." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "similar": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{entity, score, shared, shared_examples}], highest score first." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." } }, "additionalProperties": true }, "example": { "approximate": false, "as_of": "2026-09-26", "bound": 0.026139255146888734, "coverage": { "candidates": 545290, "candidates_examined": 1280, "neighbours": 4323, "scanned": 4270 }, "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "entity": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_similar_entities_v1", "similar": [ { "entity": { "name": "Intel", "normalized": "intel", "type": "ORG" }, "score": 0.06697068403908794, "shared": 514, "shared_examples": [ { "name": "Jensen Huang", "normalized": "jensen huang", "type": "PERSON" }, { "name": "China", "normalized": "china", "type": "GPE" }, { "name": "United States", "normalized": "united states", "type": "GPE" }, { "name": "AMD", "normalized": "amd", "type": "ORG" }, { "name": "Blackwell", "normalized": "blackwell", "type": "PRODUCT" } ] }, { "entity": { "name": "AMD", "normalized": "amd", "type": "ORG" }, "score": 0.06165115214405616, "shared": 404, "shared_examples": [ { "name": "Jensen Huang", "normalized": "jensen huang", "type": "PERSON" }, { "name": "China", "normalized": "china", "type": "GPE" }, { "name": "United States", "normalized": "united states", "type": "GPE" }, { "name": "Intel", "normalized": "intel", "type": "ORG" }, { "name": "NASDAQ", "normalized": "nasdaq", "type": "ORG" } ] }, { "entity": { "name": "Amazon Web Services", "normalized": "amazon web services", "type": "ORG" }, "score": 0.05581395348837209, "shared": 408, "shared_examples": [ { "name": "China", "normalized": "china", "type": "GPE" }, { "name": "United States", "normalized": "united states", "type": "GPE" }, { "name": "AMD", "normalized": "amd", "type": "ORG" }, { "name": "Intel", "normalized": "intel", "type": "ORG" }, { "name": "Blackwell", "normalized": "blackwell", "type": "PRODUCT" } ] } ], "took_ms": 436 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v2.0/atlas/relationships/events": { "get": { "operationId": "atlas_relationship_events", "summary": "Relationship events", "description": "Retrieve the World events behind one relationship, newest first.\n\nUse Relationship events to see the evidence for a relationship. Each event id is a World API event: fetch the full record, with sources and text, from World V2.0 Event details (GET /api/v2.0/events/{date}/{event_id}). For a symmetric relationship type (symmetric in Relationship types), subject and object may be sent in either order; relationship shows the relationship as stored, with its own subject and object, which may be the other way round from your request.", "tags": [ "GET DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-relationship-events" }, "x-nosible-reference-pages": [ "atlas-relationship-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "subject_type", "in": "query", "required": true, "description": "Type of the subject.", "schema": { "type": "string", "description": "Type of the subject.", "example": "ORG" } }, { "name": "subject", "in": "query", "required": true, "description": "Name of the subject.", "schema": { "type": "string", "description": "Name of the subject.", "example": "TSMC" } }, { "name": "predicate", "in": "query", "required": true, "description": "Relationship type.", "schema": { "type": "string", "description": "Relationship type.", "example": "supplier_to" } }, { "name": "object_type", "in": "query", "required": true, "description": "Type of the object.", "schema": { "type": "string", "description": "Type of the object.", "example": "ORG" } }, { "name": "object", "in": "query", "required": true, "description": "Name of the object.", "schema": { "type": "string", "description": "Name of the object.", "example": "Nvidia" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, maximum 500.", "schema": { "type": "integer", "description": "Page size. Defaults to 50, maximum 500.", "example": 3 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "description": "next_cursor from the previous page." } }, { "name": "as_of", "in": "query", "required": false, "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "schema": { "type": "string", "format": "date", "description": "Point in time (YYYY-MM-DD), from 2010-01-01 to the release's last date, which is the default (release.date_min and release.date_max in Relationship types); a date outside that range, or one that does not exist (2026-02-30), is a 422 validation_error. Only events dated on or before it count. `to` is accepted as the same parameter, as in the World API.", "example": "2024-12-31" } }, { "name": "from", "in": "query", "required": false, "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "schema": { "type": "string", "format": "date", "description": "Optional start of the evidence window (YYYY-MM-DD, inclusive). A date that does not exist (2026-02-30) is a 422 validation_error.", "example": "2020-01-01" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date", "description": "The point in time the answer is computed for." }, "count": { "type": "integer", "description": "Events in this page." }, "date_window": { "type": "object", "properties": { "archive_cutoff": { "type": "string" }, "from": { "type": "string" }, "include_live": { "type": "boolean" }, "to": { "type": "string" } }, "additionalProperties": true, "description": "The evidence window: from, to, archive_cutoff and include_live (always false)." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "[{event_id, date}], newest first." }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page, null on the last." }, "order": { "type": "string", "description": "Always desc." }, "relationship": { "type": "object", "properties": { "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "object": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "predicate": { "type": "string" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "number" } }, "additionalProperties": true, "description": "{subject, predicate, object, support, first_seen, last_seen}. support counts distinct World events inside the window; first_seen and last_seen are the earliest and latest of them." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered. The same request against the same release returns identical bytes." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "total": { "type": "integer", "description": "Supporting events inside the window." } }, "additionalProperties": true }, "example": { "as_of": "2026-09-26", "count": 3, "date_window": { "archive_cutoff": "2026-09-26", "from": "2010-01-01", "include_live": false, "to": "2026-09-26" }, "events": [ { "date": "2026-09-14", "event_id": "2026-09-14_pt_NL_v1_MYA5mXQQTDuQEUbwIAAAAAAAAAAAIgAAAAAAAAAAAAA_ekpZaUQU" }, { "date": "2026-08-10", "event_id": "2026-08-10_zh_TW_v1_nYA5mXQQTDuQEUbwQAAAAISqkAAAAAAAAAAAAAAAAAA_N7h2qMQN" }, { "date": "2026-07-26", "event_id": "2026-07-26_tr_TW_v1_TYA5mXaS7SZREUbwQAAAAAAAAAAAAKMjWAAAAAAAAAA_EOQHfPbM" } ], "next_cursor": "djMKMDU2NmUyMjFkNmZjZWUzMGQzNmE0ZDEzYzNkOTUzZTUKcmVsYXRpb25zaGlwX2V2ZW50cwo2OTViNGU5YzY2ODdkODM2CjIwMjYwNzI2OjEyNDk3NTIyCjlhZmE3MjY2OTFmYTg0OGI", "order": "desc", "relationship": { "first_seen": "2014-08-26", "last_seen": "2026-09-14", "object": { "name": "Nvidia", "normalized": "nvidia", "type": "ORG" }, "predicate": "supplier_to", "subject": { "name": "TSMC", "normalized": "tsmc", "type": "ORG" }, "support": 178 }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_relationship_events_v1", "took_ms": 0, "total": 178 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: The relationship has no supporting event inside the window, so it does not exist at that point in time.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v2.0/atlas/relationships/types": { "get": { "operationId": "atlas_relationship_types", "summary": "Relationship types", "description": "List the relationship types, entity types and date range of the graph.\n\nUse Relationship types to discover the vocabulary for the predicates filters and the date range you can ask about. It describes the release as a whole, so it takes no as_of or from.", "tags": [ "GET DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-relationship-types" }, "x-nosible-reference-pages": [ "atlas-relationship-types" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "predicate", "in": "query", "required": false, "description": "Return only this relationship type.", "schema": { "type": "string", "description": "Return only this relationship type.", "example": "supplier_to" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Entity types in the graph." }, "release": { "type": "object", "properties": { "date_max": { "type": "string", "format": "date", "description": "Last day of the graph: the latest as_of any Atlas endpoint accepts, and the date they use when you send none." }, "date_min": { "type": "string", "format": "date", "description": "First day of the graph, 2010-01-01: the earliest as_of any Atlas endpoint accepts." }, "entities": { "type": "number" }, "events": { "type": "number" }, "id": { "type": "string" }, "relationships": { "type": "number" } }, "additionalProperties": true, "description": "The graph release that answered: {id, date_min, date_max, entities, relationships, events}." }, "schema": { "type": "string", "description": "Response schema name." }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "types": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "predicate": { "type": "string", "description": "The relationship type, as the predicates filters take it." }, "symmetric": { "type": "boolean", "description": "true when the relationship has no direction: it reads the same whichever entity is named first (collaborates_with, allied_with and ceasefire_with), so either entity may have either type in subject_types and object_types. false when the two sides have different roles, as in supplier_to, where the subject supplies the object." }, "subject_types": { "type": "array", "items": { "type": "string" }, "description": "Entity types that can be the subject." }, "object_types": { "type": "array", "items": { "type": "string" }, "description": "Entity types that can be the object." }, "relationships": { "type": "integer", "description": "Relationships of this type in the whole release." } } }, "description": "The relationship types: [{predicate, definition, group, family, symmetric, subject_types, object_types, relationships}]." } }, "additionalProperties": true }, "example": { "entity_types": [ "ORG", "PERSON", "GPE", "LOC", "PRODUCT" ], "release": { "date_max": "2026-09-26", "date_min": "2010-01-01", "entities": 6727924, "events": 13011764, "id": "0566e221d6fcee30d36a4d13c3d953e5", "relationships": 32497737 }, "schema": "nosible_atlas_relationship_types_v1", "took_ms": 0, "types": [ { "definition": "The subject supplies goods or services to the named party.", "family": "supplier_relationship", "group": "supply_trade_and_transport", "object_types": [ "GPE", "ORG", "PERSON" ], "predicate": "supplier_to", "relationships": 236593, "subject_types": [ "GPE", "ORG", "PERSON" ], "symmetric": false } ] } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v2.0/atlas/entities/normalize": { "get": { "operationId": "atlas_normalize_entity", "summary": "Normalize entity", "description": "Normalize an entity name: the entity it stands for and every name that belongs to it.\n\nUse Normalize entity to turn whatever name a user typed into the normalized entity, with every recorded spelling that belongs to it. Each spelling belongs to exactly one entity, so expanding a query to these names never counts an event twice; match event mentions on match_keys to catch spellings the graph has not recorded. It describes the release as a whole, so it takes no as_of or from.", "tags": [ "GET DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/atlas-normalize-entity" }, "x-nosible-reference-pages": [ "atlas-normalize-entity" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "description": "The name to normalize. Punctuation, spacing, case and Latin accents do not matter: \"coca cola\", \"Coca-Cola\" and \"COCA COLA\" are the same name.", "schema": { "type": "string", "description": "The name to normalize. Punctuation, spacing, case and Latin accents do not matter: \"coca cola\", \"Coca-Cola\" and \"COCA COLA\" are the same name.", "example": "coca cola" } }, { "name": "type", "in": "query", "required": false, "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. Without it every type is tried and the most-mentioned answer wins; the others are listed in other_types.", "schema": { "type": "string", "description": "Entity type: ORG, PERSON, GPE, LOC or PRODUCT. Without it every type is tried and the most-mentioned answer wins; the others are listed in other_types.", "example": "ORG" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "name": { "type": "string" }, "normalized": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true, "description": "The normalized entity: {type, name, normalized}." }, "match_keys": { "type": "array", "items": { "type": "string" }, "description": "The match keys of those names (lowercase letters and digits only, Latin accents folded)." }, "names": { "type": "array", "items": { "type": "string" }, "description": "Every recorded spelling that belongs to the entity, its own name first." }, "query": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": true, "description": "The name and type you sent." }, "release": { "type": "string", "description": "Immutable id of the graph release that answered." }, "schema": { "type": "string" }, "took_ms": { "type": "integer", "description": "Server time in milliseconds." }, "other_types": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Other entity types that have the name, when type was not sent." } }, "additionalProperties": true }, "example": { "entity": { "name": "Coca-Cola", "normalized": "coca-cola", "type": "ORG" }, "match_keys": [ "cocacola", "cocacolaco", "thecocacolaco", "cocacolacompany", "thecocacolacompany" ], "names": [ "Coca-Cola", "Coca-Cola Co.", "The Coca-Cola Co.", "Coca-Cola Company", "The Coca-Cola Company", "The Coca-Cola company", "the Coca-Cola Company", "CocaCola", "Coca Cola", "Coca-Cola Co", "The Coca-Cola Co" ], "query": { "name": "coca cola", "type": "ORG" }, "release": "0566e221d6fcee30d36a4d13c3d953e5", "schema": "nosible_atlas_entity_normalize_v1", "took_ms": 0 } } } }, "400": { "description": "invalid_request: The body is not valid JSON, is missing, or the request framing is broken. A request whose parameters are the problem is a 422 validation_error. Every error body, 401 included, is {error, message, status}.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "unknown_entity: No entity of that type has that name in this release. When the name exists under another type, the message says which.\n\nnot_found: No endpoint has this path.", "x-nosible-error-codes": [ "unknown_entity", "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "405": { "description": "method_not_allowed: The path exists but not for this method (a GET to a POST endpoint, or the reverse); the Allow header lists the methods it takes.", "x-nosible-error-codes": [ "method_not_allowed" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to another release or request; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A parameter the API cannot decode or validate: a missing required parameter, an unknown parameter, a value of the wrong type or outside its range (as_of outside the release's dates, a min_support below 1), or a date that does not exist, such as 2026-02-30. The message names the parameter and what is wrong.\n\ninvalid_entity_type: The entity type is not one of ORG, PERSON, GPE, LOC or PRODUCT, in an entity or in other_types or exclude_types. For a ticker, send its company as an ORG.\n\nunknown_predicate: A relationship type is not in the graph; list them with Relationship types.\n\nunprocessable_request: Each value is valid but not together, such as from after as_of.\n\nrequest_too_broad: The request ran out of its work budget before it could answer; narrow it.", "x-nosible-error-codes": [ "validation_error", "invalid_entity_type", "unknown_predicate", "unprocessable_request", "request_too_broad" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: Too many requests for this key; wait for Retry-After.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The Atlas backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The Atlas backend could not be reached; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "unavailable: The service is busy or starting; retry after Retry-After.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_key_metering_unavailable: API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.", "x-nosible-error-codes": [ "unavailable", "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "request_timeout: The request took longer than 25 seconds; narrow it.\n\nbackend_timeout: The Atlas backend did not answer before the deadline; retry.", "x-nosible-error-codes": [ "request_timeout", "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "schemas": {} } }