Skip to main content

​
Knowledge API reference

The Knowledge API is designed for applications that need persistent indexed reference material rather than one-time prompt attachments.

​
Resource concepts

The Alpha v1 architecture includes resources for Knowledge bases, sources/files, ingestion state, and retrieval queries. Confirm exact routes and schemas in the active OpenAPI surface.

​
Knowledge base

A Knowledge base should have a clear owner:
  • personal account
  • Project
  • organization
Ownership determines authorization, policy, and billing/storage context.

​
Add a source

A source can be a supported uploaded file, repository, URL, or other enabled source type. Source creation is asynchronous when extraction/indexing is required. The create operation should not be treated as “retrieval-ready” until processing state confirms it.

​
Query

A retrieval query can carry concepts such as:
  • query text
  • result limit
  • source filters
  • project/organization context
Returned results should preserve source identity and location metadata when available so the caller can display or verify provenance.

​
Permissions

Semantic relevance never bypasses authorization. A credential can only retrieve from Knowledge it is allowed to access.

​
Index state

Applications that ingest sources should monitor ready/failed/stale state and expose meaningful recovery rather than assuming every upload indexed successfully.

​
Embeddings

The Developer Platform can expose embedding capability separately from managed Knowledge. Do not assume a Knowledge base uses a specific public embedding model unless the contract says so.

Knowledge & RAG

Understand the ingestion and retrieval architecture behind the API.