Overview

What is Graphon Engine?

Graphon Engine is a collection of services and storage components that run together as a cluster. The REST API receives requests. The Blob Indexer uses GPUs to understand each file and find connections between files. The Query Engine runs Search, Answer, and Research. A database holds metadata, a blob cache speeds up data access, and blob storage keeps file content. Blobs are stored units of file data.

How Graphon Engine organizes your data

A cluster is one Engine deployment with its own base URL. It contains namespaces, which isolate tenants. A tenant is a customer or application whose data must stay separate. Each namespace contains collections. A collection holds the files that one Search or Answer request can use. Answer can respond to a question even when the facts are spread across many files.

For example, the acme-corp namespace contains an incident-logs collection. Add incident reports, screenshots, or recordings to that collection. Search can locate an incident. Answer can explain its cause from several reports and cite each source.

A file has an ID, a logical path, a source, metadata, and a processing status. Its path might be /incidents/checkout.txt. Its source supplies the content. The path organizes the collection and does not have to match the source location.

GET /namespaces/acme-corp/collections/incident-logs/files/fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3 HTTP/1.1
Host: graphon.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>

{
  "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
  "path": "/incidents/checkout.txt",
  "status": "ready",
  "stage": null,
  "source": {
    "type": "inline",
    "content_type": "text/plain",
    "bytes": 118
  },
  "metadata": {
    "environment": "production",
    "service": "checkout"
  },
  "created_at": "2026-10-06T12:00:00Z",
  "updated_at": "2026-10-06T12:01:00Z"
}

Adding files to a collection

Add a file with one request to the collection’s files endpoint. The request names the file’s path and its source. The source tells Engine where the file bytes come from.

POST /namespaces/acme-corp/collections/incident-logs/files HTTP/1.1
Host: graphon.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
Idempotency-Key: checkout-txt-1

{
  "path": "/incidents/checkout.txt",
  "source": {
    "type": "inline",
    "content_type": "text/plain",
    "text": "Checkout stalled because the service exhausted its connection pool. Increase the pool size before the next deployment."
  }
}

Engine replies right away. Inline and URI requests return 202 Accepted. An upload returns 201 Created with the upload URL. Each response holds the new file and a job. Save their IDs.

Processing continues after the response. The file starts as pending while it waits for its bytes or an indexer. During indexing, GPUs understand the file’s contents and link it to related files. A ready file can appear in Search and Answer. If processing stops, the file is failed. Read its error and its job.

Engine sends a file.status_changed event at each change. Jobs and events explain how to track completion.

Searching and answering from collections

Each operation addresses one collection. Choose Search to build a results interface. Choose Answer to answer a question from the files. Choose Research for a long question that should not hold a connection open.

Control who can retrieve

An API key authorizes your application. Its scope identifies the namespace or collections it can reach. Its actions identify the operations it can perform. Authentication explains the complete contract.

For per-user retrieval, enable access control on a collection. Your application authenticates each person and sends their principals: exact user and group names. Engine applies access rules before content can enter Search results or answers. See Principals and access rules.

Start building

Use the Get started guide for a complete HTTP walkthrough with inline text. It requires a reachable cluster and a cluster API key. No external storage account is needed.

Read Concepts for the data model. Use the API reference for request fields, response fields, errors, and examples. Each example uses https://engine.example.com; replace it with your cluster URL.