---
title: "Retrieve Y2 Global Knowledge"
description: "Searches shared Y2 knowledge and, when requested, the key's workspace knowledge. Y2 determines access from the key. The request cannot supply a user or workspace ID. Results include source IDs and citations. They omit provider and access-control attributes. This operation requires a workspace-bound API key with `intel:knowledge`. It does not support x402. Agent Y2 keys continue to use `agent:y2`. The agent may invoke this retrieval tool internally when the workspace is entitled to Chat."
canonical: https://y2.dev/docs/api/reference/global-knowledge/retrieveGlobalKnowledgeV2/
---

Endpoint Reference[Global Knowledge](https://y2.dev/docs/api/reference/global-knowledge)

# Retrieve Y2 Global Knowledge

Searches shared Y2 knowledge and, when requested, the key's workspace knowledge. Y2 determines access from the key. The request cannot supply a user or workspace ID. Results include source IDs and citations. They omit provider and access-control attributes. This operation requires a workspace-bound API key with \`intel:knowledge\`. It does not support x402. Agent Y2 keys continue to use \`agent:y2\`. The agent may invoke this retrieval tool internally when the workspace is entitled to Chat.

`POST https://api.y2.dev/api/v2/intel/knowledge/retrieve`

- Operation ID: `retrieveGlobalKnowledgeV2`
- Required scopes: `intel:knowledge`
- Contract: https://y2.dev/openapi.json

## Request body

`application/json`: `GlobalKnowledgeRetrievalRequest` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes |  |
| `knowledgeMode` | `shared`, `workspace`, `combined` | No | Narrows retrieval to shared, key-workspace, or both authorized corpora. |
| `documentKinds[]` | array of `report_chunk`, `signal_assessment`, `report_graph_component`, `source_document_chunk` | No |  |
| `entityIds[]` | array of string | No |  |
| `incidentIds[]` | array of string | No |  |
| `subjectKeys[]` | array of string | No |  |
| `domains[]` | array of `cyber`, `markets`, `geopolitical`, `operational`, `supply_chain`, `policy`, `military`, `technology`, `other` | No |  |
| `priorities[]` | array of `low`, `medium`, `high`, `critical` | No |  |
| `generatedAfter` | integer | No | Inclusive lower bound as Unix milliseconds. |
| `generatedBefore` | integer | No | Inclusive upper bound as Unix milliseconds. |
| `limit` | integer | No |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Authorized, current-manifest Global Knowledge results. | `GlobalKnowledgeRetrievalResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |
| 503 | Y2 Global Knowledge is disabled or its retrieval provider is unavailable. |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]` | array of `GlobalKnowledgeResult` |  |
| `data[].documentId` | string |  |
| `data[].rank` | integer |  |
| `data[].documentKind` | `report_chunk`, `signal_assessment`, `report_graph_component`, `source_document_chunk` |  |
| `data[].title` | string |  |
| `data[].excerpt` | string |  |
| `data[].sectionPath` | string |  |
| `data[].source` | object |  |
| `data[].ontology` | object |  |
| `data[].canonicalRefs[]` | array of `GlobalKnowledgeCanonicalReference` |  |
| `data[].episode` | object |  |
| `data[].inferenceKind` | string |  |
| `data[].generatedAt` | integer |  |
| `data[].validFrom` | integer |  |
| `data[].validTo` | integer |  |
| `data[].citationUrls[]` | array of string (uri) |  |
| `meta` | object |  |
| `meta.count` | integer |  |
| `meta.limit` | integer |  |
| `meta.knowledgeMode` | `shared`, `workspace`, `combined` |  |