API reference
Base URLs, authentication, HTTP conventions, and a first request.
Use the Graphon Engine HTTP API to manage namespaces, collections, and files, then search a collection or answer questions from it. Every operation page documents parameters, response fields, errors, and examples.
Base URL and version
Each cluster has its own base URL. This reference uses https://engine.example.com. Replace it with your cluster URL; do not send examples to that placeholder. Routes have no /v1 prefix. GET /info reports api_version.
GET https://engine.example.com/health
GET /health HTTP/1.1
Host: engine.example.com200 OK
{
"status": "ok"
}Health and Ready do not require authentication. Every other route requires an API key. A failed readiness check returns 503. Use Info to check supported modes, URI schemes, and event types.
Authentication
Send Authorization: Bearer <GRAPHON_ENGINE_API_KEY> on authenticated requests. X-API-Key is also supported. Use the full key secret, not its key_ management ID. Use HTTPS except on loopback.
Request header
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>Authentication explains cluster, namespace, and collection keys, their actions, and revocation. A key identifies the application. Principals and access rules provide per-reader retrieval within enforced collections.
Request and response conventions
| Convention | Contract |
|---|---|
JSON | Use Content-Type: application/json. Fields use snake_case. Unknown request fields fail validation. |
Timestamps | ISO 8601 UTC strings. |
Byte counts | Integers for ordinary file sizes. Large usage totals are decimal strings. |
IDs and names | Namespace and collection URL parameters accept immutable IDs or names. |
File paths | Case-sensitive, leading slash, no trailing slash. Use a fil_ ID or encoded path in a file route. |
Correlation | Send optional X-Request-Id. Responses echo it in x-request-id. Responses return x-engine-request-id, the Engine request ID. Error bodies include the same ID as request_id. |
Use Pagination and idempotency for continuation and write retries. Read Limits before batching or sending large content.
Success and completion
| Status | Meaning |
|---|---|
200 OK | A read or synchronous update completed. exist_ok can return an existing resource. |
201 Created | A resource was created. The response can include a Location header. |
202 Accepted | Work was accepted. Follow the returned job to completion through events. |
204 No Content | A synchronous delete completed. There is no response body. |
A 202 is not a ready signal. Events deliver job, file, collection, and research status changes. Use resource GET calls to recover after a missed delivery.
Errors use one error envelope. Each operation lists the errors that apply to it.
Choose your next request
- Create namespace establishes a tenant boundary.
- Create collection groups files for retrieval.
- Add file submits content.
- Search collection retrieves ranked spans.
- Answer collection generates an answer with sources.
- Get started connects all five into one walkthrough.
Download the Engine OpenAPI document for the machine-readable HTTP schema. Examples in this site are static and do not execute API calls.