Concepts

Workspace

The shared home for your team and its data.

A workspace owns buckets, API keys, and memberships. Select a workspace before you create a bucket or issue a key. A person can belong to more than one workspace, with a different role in each.

Members use roles such as Viewer, Editor, and Admin. API keys also have roles and belong to a workspace. For example, your support team can share a workspace while a backend service uses a workspace key to access its buckets.

Bucket

A named container for related objects.

A bucket groups objects in a workspace, much like an S3 bucket. You choose its provider and location when you create it. Separate buckets can hold support files, product media, or data for different customers.

Bucket names are case-sensitive and unique within a workspace. Use 1–255 ASCII letters, digits, periods, underscores, or hyphens, except the exact names . and ... Rename preserves the bucket ID and data. JSON addresses that ID. S3 uses the current name on your workspace endpoint.

The bucket’s indexing setting controls whether Graphon indexes its objects. With indexing enabled, Graphon prepares the content for search and query as objects arrive. With indexing disabled, the bucket provides object storage only. Choose this setting when you create the bucket. You cannot change it later.

Object

The file you store, identified by a key inside a bucket.

An object combines file bytes with a key, such as policies/refunds.pdf. The key identifies the object within its bucket. The same key can exist in another bucket without referring to the same file.

Keys can contain slashes to organize related files under a prefix. For example, policies/ groups policy documents without creating a separate bucket. Objects can hold documents, images, audio, video, or structured records. Store, read, and list them through the API, CLI, or supported S3 operations.

Indexing status

How far each file has come on its way into search.

In a bucket with indexing enabled, each object version has an indexing status. A new version goes through four unfinished states in order. In preparing, Graphon copies the file for the index. In sending, Graphon gives the file to the index. In queued, the file waits for an index worker. In indexing, the index reads the content and builds the index. The version then stops in one of three finished states: ready, failed, or unsupported.

A ready version is searchable. A failed version stopped with an error, such as a file that is not a readable PDF. An unsupported version is one that Graphon does not index, for example because of its size or its metadata. When a step fails for a short time, Graphon tries it again by itself. The status then shows the number of retries and the last error.

When you write a new version of a key, a read returns the new file at once. Search keeps the older ready version until the new version is ready. If the new version fails, search keeps the older version. The searchable field names the version that search uses now.

Every object response has the status in its indexing field. Get bucket index status returns the counts for a bucket and lists its unfinished versions in the order they will finish. With a filter, it lists the failed or unsupported versions with the reason for each. The Objects and Indexing tabs in the app and graphon buckets index-status show the same information.

Tenant partition

A way to organize data by the customers of your application.

A tenant is your application’s customer or organization. If your support app serves Acme and Northwind, each customer should see only its own files. This boundary is different from a Graphon workspace, which can serve your whole application.

Use a key prefix per tenant in one bucket, or a separate bucket per tenant. Your backend checks the signed-in customer and selects the correct prefix or bucket. A prefix is an organization convention, not an access control by itself. Keep the workspace API key in your backend, because it can access other buckets in that workspace.

Query modes

Choose between finding content and getting an answer from it.

A search result helps your application find relevant material. An answer uses that material to respond to a question. Choose the result that your user or agent needs: matching content, passages for a prompt, or an answer with sources.

All four run against one target, a bucket with indexing enabled or a dataset, and each is one call on the Graphon API. Search and Answer return on the same call and store nothing. Research returns a run that stays readable until expiresAt, seven days past the end.

Citations

A connection between an answer and the content that supports it.

A citation identifies the source behind a statement in an answer. It lets the reader return to the original object and inspect the supporting content. This is useful when an answer combines information from several files.

For example, an answer about refund timing can cite the refund policy instead of leaving the reader to guess where the claim came from. In your application, show the cited source alongside the answer so a reader can check its context. A source reference helps someone verify a claim; it does not replace that review.

Graphon writes each citation as a marker such as [[SRC:0001]] inside the answer. The source with the same ref carries the object key, the version that was read, and the place inside it, so a link can open the file at its page or its time range. A source marked as not cited was read but not used.

Dataset

A read-only set of documents that Graphon curates and every workspace can query.

A dataset holds documents that Graphon curates from a public source, such as court opinions or product pages. Graphon keeps the documents indexed. Your workspace uploads nothing, and a dataset counts toward none of its storage.

Query a dataset with the same calls as a bucket. Send its id, which starts with dst, as target in place of a bucket id, which starts with bkt. A dataset query counts toward your plan’s queries per month. A dataset is free, or paid with a monthly price of its own.