Add file

Add a file, or replace the current file at the same logical path.

POST/namespaces/{namespace}/collections/{collection}/files

PermissionCluster key, or a scoped key with write on this collection. Key scopes and actions.

Send Idempotency-Key. Retry the same logical request with the same key and body. Idempotency records remain available for replay for 24 hours.
URI and inline sources return 202 with a file and job. An upload source returns 201 with a file, job, and upload URL.
For upload, PUT bytes to upload.url before upload.expires_at. Do not send your Engine key to the upload host.
Adding a URI copies its current bytes. A later change in the object store does not change the index. Add the same path again to replace its content.
A replacement becomes searchable when processing succeeds. Inspect the new file’s job for failures.
Use events webhooks for live status. Read the job to inspect its current state or recover after a missed event.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs/files

POST /namespaces/acme/collections/incident-logs/files HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7

{
  "path": "/reports/incident.txt",
  "source": {
    "type": "inline",
    "content_type": "text/plain",
    "text": "Checkout requests stalled because the database connection pool was exhausted."
  },
  "metadata": {
    "environment": "production"
  }
}

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

202

An inline or URI file was accepted for indexing. The file becomes searchable after processing succeeds.

{
  "file": {
    "id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
    "path": "/reports/incident.txt",
    "status": "indexing",
    "source": {
      "type": "inline",
      "content_type": "text/plain",
      "bytes": 77
    },
    "metadata": {
      "environment": "production"
    },
    "created_at": "2026-10-06T10:00:00Z",
    "updated_at": "2026-10-06T10:00:00Z"
  },
  "job": {
    "id": "job_01K6Q6N7D8E9F0G1H2J3K4M5N6",
    "type": "index_file",
    "status": "running",
    "namespace": "acme",
    "collection": "incident-logs",
    "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
    "error": null,
    "created_at": "2026-10-06T10:00:00Z",
    "updated_at": "2026-10-06T10:00:00Z"
  }
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

Headers

Idempotency-Keystringrequired

Unique key for this logical operation. Reuse it only with the same request for retries. Retained for 86,400 seconds. A changed body returns idempotency_conflict.

Request body

metadatamap<string, JSON value>optional

Application data attached to the file, as a JSON object. Values may be any JSON value. A filter can read metadata.<key> only when the collection lists that key in its metadata fields.

pathstringrequired

Case-sensitive path within the collection, such as /reports/incident.txt. Start with / and omit a trailing /. Maximum 1,024 UTF-8 bytes. Empty, dot, parent, and control-character segments are invalid.

sourceobjectrequired

Where the file bytes come from. Choose the uri, upload, or inline variant. Each variant has its own required fields.

Responses

202File accepted

An inline or URI file was accepted for indexing. The file becomes searchable after processing succeeds.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

fileobjectrequired

File accepted for processing. Inspect its status before retrieval.

jobobjectrequired

Durable index_file job for this add or replacement.

uploadobjectoptionalaccepts null

Present only for upload sources. PUT the file bytes to its URL before its expiry time.

201Upload created

The upload variant returns a signed URL. PUT the file bytes there before expires_at.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

Locationstringrequired

The path of the new resource, by ids.

fileobjectrequired

File accepted for processing. Inspect its status before retrieval.

jobobjectrequired

Durable index_file job for this add or replacement.

uploadobjectoptionalaccepts null

Present only for upload sources. PUT the file bytes to its URL before its expiry time.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

400invalid_uri

The source URI uses an unsupported scheme or an invalid location.

What to do: Check GET /info for supported schemes and correct the URI.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409idempotency_conflict

This idempotency key was already used with a different request body.

What to do: Reuse the original body for a retry, or choose a new key for a new operation.

409operation_in_progress

An unfinished operation conflicts with this request.

What to do: Inspect the existing job and wait for its completion event before retrying.

409limit_exceeded

The operation would exceed a documented size or count limit.

What to do: Reduce the input or resource count. This is not a tenant billing limit.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

422storage_unreachable

The cluster cannot read the source object.

What to do: Check that the object exists and the cluster’s connector can read it, then retry.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown