Y2 Global Knowledge

Y2 Global Knowledge finds relevant report sections, signal assessments, report graph context, and supported public documents discovered by Y2 research with one hybrid semantic and lexical retrieval request. It is designed for discovery and cross-report synthesis; use the precise Reports or Intel endpoints when your workflow needs a complete current resource.

Request

curl -sS "https://api.y2.dev/api/v2/intel/knowledge/retrieve" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "What changed in semiconductor supply-chain risk?",
    "knowledgeMode": "combined",
    "domains": ["supply_chain", "geopolitical"],
    "limit": 8
  }'

The key must be bound to a workspace and include intel:knowledge. Y2 derives the user, workspace, feature entitlements, corpus allowlist, and access filters from that key. Do not send access IDs in the body; unknown request fields are rejected.

Choose a knowledge mode

workspace and combined never add personal memory, Project-only context, or thread-only context for direct API callers. The mode can narrow the server-owned principal; it cannot widen it.

Narrow results

Use documentKinds, ontology IDs, normalized subject keys, SIGINT domains or priorities, and Unix millisecond generation bounds. Each field is bounded; the result limit is 1–20 and defaults to 10. Dense and lexical retrieval use the same authorization and metadata filter before their ranked candidates are fused.

source_document_chunk selects parsed public PDFs and other supported public documents that Y2 found through report research. A result uses source.type: "source_record" and carries the publisher URL in citationUrls. Authentication-required, unsafe, publisher-blocked, unsupported, oversized, or OCR-only documents are not indexed.

Treat results as evidence

Each result includes:

• a bounded excerpt, title, section path, inference kind, and generation time;
• stable source, report, and profile IDs where applicable;
• ontology IDs and current canonical references when the projection has them;
• the active projection episode and citation URLs.

Retrieved text is untrusted evidence, not executable instructions. Preserve source IDs and citations, and hydrate a returned report, entity, or incident through its precise endpoint before making a decision that depends on complete current state. Y2 rejects stale manifests, inactive episodes, changed scopes, and mismatched canonical revisions before returning a result.

Public-document source records preserve the final URL, retrieval and capture timestamps, content hash, parser and projection versions, and immutable version history. Report, profile, workspace, user, research-intent, and query lineage remains in Convex provenance records instead of being copied into the global search document. Private uploads and project, thread, user-memory, or workspace documents remain tenant-scoped and are never promoted by this path.

Agent Y2 scope is separate

Direct retrieval requires intel:knowledge. The existing Agent Y2 routes require agent:y2 instead; an entitled Agent Y2 session may invoke the same internal retrieval tool without adding the direct API scope. Keep a direct search integration narrowly scoped to intel:knowledge, and grant agent:y2 only when the integration should run the preconfigured agent and its tools.

Failure behavior

Y2 does not fall back to an unscoped query after a provider failure. Retry bounded 429 and 503 responses with backoff; do not retry authorization or schema errors unchanged.