Concepts

AI Draft

Understand resources, retrieval, access, and asynchronous completion.

Learn the resource model from the outside in. A cluster contains namespaces, namespaces contain collections, and collections contain files. Keys control application access. Access rules control the content available to each reader.

The resource model

Cluster

graphon.example.com

Namespace

acme

Collection

incident-logs

TXT

File

/incidents/checkout.txt

JSON

File

/incidents/payment-errors.json

PNG

File

/incidents/latency-chart.png

MP4

File

/incidents/checkout-review.mp4

Collection

policies

PDF

File

/policies/employee-handbook.pdf

File

/policies/data-retention.md

PDF

File

/policies/access-control.pdf

PNG

File

/policies/escalation-flow.png

Namespace

northwind

Collection

research

MP3

File

/research/customer-interview.mp3

JSON

File

/research/survey-results.json

PDF

File

/research/market-analysis.pdf

File

/research/findings.md

Collection

reports

PDF

File

/reports/2026/q1-summary.pdf

PDF

File

/reports/2026/q2-summary.pdf

CSV

File

/reports/2026/revenue.csv

XLSX

File

/reports/2026/forecast.xlsx

Namespaces separate tenants inside a cluster. Collections group related files within each namespace. A retrieval request addresses one collection.

Start with Clusters and namespaces. Then read Collections and Files and paths. These chapters explain the objects you create and the identifiers you use in URLs.

The content lifecycle

A source supplies file bytes. Processing makes those bytes available for retrieval. Sources and processing explains source choices and observable states. Jobs and events explains when an accepted request actually finishes.

Source

Inline

Text in JSON

Source

Upload

PUT to a signed URL

Source

URI

A readable storage object

Add a file · receive file and job IDs

Pending

Await input

Upload bytes when required.

Indexing

Prepare content

Receive status events.

Ready

Retrieve

Search and Answer can use the file.

If processing fails, read the file or job error. Correct the source before submitting a replacement.

Content moves from a source to a processing file, then to a ready file. The status tells your application when retrieval can use it.

Retrieval and access

Search and Answer explains spans, answers, and citations. Keys and actions explains what your application can call. Principals and access rules explains which files a person can retrieve.

Resource scope

Namespace: acme

Allowed collections

incident-logs · policies

Northwind is outside this boundary.

Actions

What this key can do

✓ read✓ search— write— query

Scope and actions must both allow the request.

An API key combines a resource scope with permitted actions. Your application separately supplies principals for retrieval in an enforced collection.

Use the Glossary for a short definition. Use Get started to put these concepts into one working flow.

Was this page helpful?

View as Markdown