Graphon Engine

Glossary

AI Draft

Definitions of Engine resources, retrieval, permissions, and completion.

Definitions of the terms used in Graphon Engine requests, responses, and guides. Follow each link for examples and the full contract.

Resources

TermDefinition

Cluster

One Engine deployment, with one base URL, a major API version, and a set of capabilities.

Namespace

A named tenant isolation boundary containing collections. Its name is unique in the cluster.

Tenant

An application customer or data owner isolated from other customers. A namespace provides that boundary.

Collection

A named set of files that Search and Answer address together.

File

A content resource in a collection with an ID, logical path, source, metadata, and processing status.

Path

A case-sensitive UTF-8 file name inside a collection, beginning with a slash.

Prefix

The beginning of a path. A prefix ending with a slash selects a directory-like set of paths.

Source

The content input for a file: inline text, an upload, or a supported storage URI.

Metadata

A JSON object of application facts attached to a file. Metadata fields can be used in retrieval filters.

Resource ID

An immutable public identifier, such as ns_, col_, fil_, key_, job_, rsr_, evt_, or acr_ with a ULID suffix.

Retrieval

TermDefinition

Search

An operation that returns ranked files or passages with their spans.

Answer

An operation that returns a natural-language answer grounded in one collection, with optional sources.

Research run

An Answer that runs on its own. Start it, follow its events or read it, and cancel it if needed.

Span

A file ID and a place in that file: pages from 1, chars or seconds from 0, from start to end, or the whole file. It holds no content.

Read spans

An operation that returns the content of up to 50 spans in the parts that include names: text (the text, or transcript lines), raw (the pages, the image, or a clip), or file (the whole file).

Citation

An answer marker such as [[SRC:0001]] that names the source whose ref is SRC:0001.

Processing profile

The collection’s keyword, semantic, and graph flags.

Index generation

An opaque identifier for indexed content used by a retrieval request.

Filter

A typed condition that selects application data. A filter does not authorize a reader.

Cursor

An opaque continuation token returned by a list or Search response.

Access and completion

TermDefinition

API key

A secret credential that authenticates a program. Engine key secrets begin with gek_.

Scope

The cluster, namespace, or named collections that a key can reach.

Action

A permitted operation category: read, write, search, or query.

Principal

An exact user or group string supplied by the trusted application, such as user:u_8812.

Access rule

A list of readers allowed to retrieve content at a folder prefix or file path.

Governing rule

The single rule that decides whether a reader can retrieve a file.

Sealed rule

A folder rule that governs all descendants and overrides rules below it.

Job

The public record of an operation that continues after the request response.

Event

A status-change notification for a job, file, collection, or research run.

Webhook

An HTTPS receiver that a key registers with a scope. Engine POSTs the signed events in that scope to it.

Delivery log

The 30-day record of the events that one webhook got, with every attempt. Replay queues its events again.

Idempotency key

A caller-chosen request header that identifies one logical write for safe replay.

Continue with Concepts or the complete Get started walkthrough.

Was this page helpful?
View as Markdown