--- title: Get started description: Create a namespace, add inline text, and retrieve your first answer with HTTP. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Get started Create a namespace and collection, add a short incident report, then retrieve evidence and an answer. Each step shows an HTTP request and an illustrative response. ## Before you begin You need a reachable Graphon Engine cluster and a **cluster key** from its operator. A cluster key can create namespaces. Use it for this walkthrough. In an application, issue narrower keys after provisioning. Replace `engine.example.com` with the host of your cluster. Replace `` with your key in every `Authorization` header. Requests use HTTPS, except local loopback development. The examples are static; this docs site does not send them. Configure a status receiver before adding files. The operator adds its URL to the cluster events configuration. Follow [Handle jobs and events](/engine/guides/jobs-and-events) for setup and signature checks. This walkthrough uses a completion event, then one status read to confirm the result. > **Example values** > > Resource IDs, timestamps, generation values, scores, and timings below are illustrative. Use the values returned by your own requests. ## 1. Check your cluster Call [Info](/engine/reference/info) to check authentication and discover the capabilities of this cluster. Confirm that `search.modes` includes `semantic` and `query.modes` includes `standard`. **GET https://engine.example.com/info** ```http GET /info HTTP/1.1 Host: engine.example.com Authorization: Bearer ``` **200 OK** ```json { "name": "graphon-engine", "api_version": "1", "auth": { "required": true }, "storage": { "primary": "graphon", "schemes": [ "gs", "graphon" ] }, "search": { "modes": [ "keyword", "semantic" ] }, "query": { "modes": [ "standard" ] }, "events": { "webhooks": 1, "types": [ "job.updated", "file.status_changed", "collection.status_changed" ] } } ``` `events.webhooks` reports the number of configured receivers. If it is zero, ask the operator to configure the receiver before relying on live notifications. A `401` means the key is missing, invalid, or revoked. ## 2. Create a namespace A namespace is a tenant boundary. [Create namespace](/engine/reference/create-namespace) makes `acme`. The name becomes part of the URLs used below. An `Idempotency-Key` identifies this logical write; reuse it only when retrying the same request. **POST https://engine.example.com/namespaces** ```http POST /namespaces HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json Idempotency-Key: quickstart-acme-namespace { "name": "acme", "display_name": "Acme", "exist_ok": true } ``` **201 Created · Location: /namespaces/ns_01J8Z3K4N5P6Q7R8S9T0V1W2X3** ```json { "id": "ns_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "name": "acme", "display_name": "Acme", "usage": { "collections": 0, "files": 0, "source_bytes": "0", "index_bytes": "0" }, "created_at": "2026-10-06T12:00:00Z", "updated_at": "2026-10-06T12:00:00Z" } ``` Retain the returned `name` and `id`. `exist_ok: true` returns `200 OK` with the existing namespace if the name already exists. It does not update that namespace. ## 3. Create a collection A collection is the set of files that Search and Query use together. [Create collection](/engine/reference/create-collection) makes `incident-logs`. The default processing profile enables keyword, semantic, and graph processing. **POST https://engine.example.com/namespaces/acme/collections** ```http POST /namespaces/acme/collections HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json Idempotency-Key: quickstart-incident-collection { "name": "incident-logs", "display_name": "Incident logs", "exist_ok": true, "access_control": "off" } ``` **201 Created · Location: /namespaces/ns_01J8Z3K4N5P6Q7R8S9T0V1W2X3/collections/col_01J8Z3K4N5P6Q7R8S9T0V1W2X3** ```json { "id": "col_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "namespace": "acme", "name": "incident-logs", "display_name": "Incident logs", "status": "empty", "access_control": "off", "processing": { "keyword": true, "semantic": true, "graph": true }, "index_generation": null, "file_counts": { "pending": 0, "indexing": 0, "ready": 0, "failed": 0 }, "created_at": "2026-10-06T12:00:00Z", "updated_at": "2026-10-06T12:00:00Z" } ``` The new collection is `empty`. This walkthrough uses `access_control: "off"`, so Search and Query omit `principals`. If an existing collection uses `enforced`, use a fresh collection name or follow the [access guide](/engine/guides/access-rules). ## 4. Add a file [Add file](/engine/reference/add-file) accepts inline text without a storage connector. The path starts with `/`. Metadata adds fields that your application can use in filters. **POST https://engine.example.com/namespaces/acme/collections/incident-logs/files** ```http POST /namespaces/acme/collections/incident-logs/files HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json Idempotency-Key: quickstart-checkout-report-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." }, "metadata": { "environment": "production", "service": "checkout" } } ``` **202 Accepted** ```json { "file": { "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "status": "indexing", "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:00:00Z" }, "job": { "id": "job_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "type": "index_file", "status": "running", "namespace": "acme", "collection": "incident-logs", "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "error": null, "created_at": "2026-10-06T12:00:00Z", "updated_at": "2026-10-06T12:00:00Z" } } ``` Save `file.id` and `job.id`. The file is processing. The response omits the write-only `source.text` and reports its UTF-8 byte count. Repeating this request with the same idempotency key returns the same result. A new request at the same path replaces the file content. See [Add a file](/engine/guides/add-a-file) for upload, storage URI, replacement, and failure examples. ## 5. Confirm the file is ready *Illustration: The add request returns a file ID and job ID. A configured receiver receives a signed status event. Use one status read after completion, or to recover after a missed event.* Wait for a verified `file.status_changed` event whose `file_id` matches your file and whose `data.status` is `ready`. The receiver must check the signature and deduplicate the event before using it. The event body looks like this: **Incoming file.status_changed event** ```json { "id": "evt_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "type": "file.status_changed", "occurred_at": "2026-10-06T12:01:00Z", "cluster": "graphon-engine", "namespace": "acme", "collection": "incident-logs", "job_id": "job_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "data": { "status": "ready", "previous_status": "indexing" } } ``` Read the [job](/engine/reference/get-job) once to confirm completion. This is a one-time check, not a polling loop. A missed event can use the same read to recover current state. **GET https://engine.example.com/jobs/job_01J8Z3K4N5P6Q7R8S9T0V1W2X3** ```http GET /jobs/job_01J8Z3K4N5P6Q7R8S9T0V1W2X3 HTTP/1.1 Host: engine.example.com Authorization: Bearer ``` **200 OK** ```json { "id": "job_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "type": "index_file", "status": "succeeded", "namespace": "acme", "collection": "incident-logs", "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "error": null, "created_at": "2026-10-06T12:00:00Z", "updated_at": "2026-10-06T12:01:00Z" } ``` Read the [file](/engine/reference/get-file) when you need its current source or metadata. Continue when it is ready. If the job failed, read `error.code` and `error.message`, correct the source, and submit a new add request. **GET https://engine.example.com/namespaces/acme/collections/incident-logs/files/fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3** ```http GET /namespaces/acme/collections/incident-logs/files/fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3 HTTP/1.1 Host: engine.example.com Authorization: Bearer ``` **200 OK** ```json { "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "status": "ready", "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" } ``` ## 6. Search for evidence [Search collection](/engine/reference/search-collection) returns ranked evidence. `semantic` matches meaning, so the question does not need the same wording as the report. The default result unit groups evidence by file. **POST https://engine.example.com/namespaces/acme/collections/incident-logs:search** ```http POST /namespaces/acme/collections/incident-logs:search HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "Why are checkout requests hanging?", "mode": "semantic", "limit": 10 } ``` **200 OK** ```json { "request_id": "req_example_search", "index_generation": "generation-example", "execution": { "mode": "semantic", "interpretation": "literal", "stages": [ "semantic" ] }, "results": [ { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "content_type": "text/plain", "rank": 1, "score": 0.81, "matched_by": [ "semantic" ], "evidence": [ { "kind": "text", "text": "Checkout stalled because the service exhausted its connection pool.", "location": { "char_start": 0, "char_end": 67 } } ] } ], "timing_ms": { "retrieval": 34, "total": 47 }, "warnings": [], "next_cursor": null } ``` Use `file_id` and `path` to identify the source. `evidence` contains supporting text and its location. `score` ranks these results; it is not a confidence percentage. `next_cursor: null` means there is no next page. ## 7. Ask a question [Query collection](/engine/reference/query-collection) writes an answer from the collection. Keep `return_sources: true` to receive the source map for citations. **POST https://engine.example.com/namespaces/acme/collections/incident-logs:query** ```http POST /namespaces/acme/collections/incident-logs:query HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "Why did checkout stall?", "mode": "standard", "return_sources": true } ``` **200 OK** ```json { "request_id": "req_example_query", "answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].", "mode": "standard", "sources": { "[SRC:0001]": { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "score": 0.81, "is_cited": true, "evidence": { "kind": "text", "text": "Checkout stalled because the service exhausted its connection pool.", "location": { "char_start": 0, "char_end": 67 } } } } } ``` The answer marker `[[SRC:0001]]` maps to the key `[SRC:0001]` in `sources`. Render that marker as a citation to the file and evidence. Use your actual answer and sources; generated wording can vary. ## Next steps - [Add and replace files](/engine/guides/add-a-file) with inline, upload, or URI sources. - [Filter and paginate results](/engine/guides/filter-and-paginate) for a results interface. - [Isolate tenants and issue keys](/engine/guides/tenant-keys) before connecting application customers. - [Apply access rules](/engine/guides/access-rules) for per-user retrieval. - [Handle jobs and events](/engine/guides/jobs-and-events) for completion and recovery. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.