---
title: API reference
description: Base URLs, authentication, HTTP conventions, and a first request.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# API reference

Use the Graphon Engine HTTP API to manage namespaces, collections, and files, then Search or Query a collection. 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**

```http
GET /health HTTP/1.1
Host: engine.example.com
```

**200 OK**

```json
{
  "status": "ok"
}
```

Health and Ready do not require authentication. Every other route requires an API key. A failed readiness check returns `503`. Use [Info](/engine/reference/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**

```http
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
```

[Authentication](/engine/reference/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 return x-request-id. Error bodies include request_id. |

Use [Pagination and idempotency](/engine/reference/pagination) for continuation and write retries. Read [Limits](/engine/reference/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](/engine/reference/events) deliver job, file, and collection status changes. Use resource GET calls to recover after a missed delivery.

Errors use one [error envelope](/engine/reference/errors). Each operation lists the errors that apply to it.

## Choose your next request

- [Create namespace](/engine/reference/create-namespace) establishes a tenant boundary.
- [Create collection](/engine/reference/create-collection) groups files for retrieval.
- [Add file](/engine/reference/add-file) submits content.
- [Search collection](/engine/reference/search-collection) retrieves evidence.
- [Query collection](/engine/reference/query-collection) generates an answer with sources.
- [Get started](/engine/get-started) connects all five into one walkthrough.

Download the [Engine OpenAPI document](/engine/openapi.json) for the machine-readable HTTP schema. Examples in this site are static and do not execute API calls.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.