HelixDB Docs

Reference

The HelixDB HTTP API accepts operation-tree queries at POST /v2/query, Cypher statements at POST /v2/cypher, and read-only Cypher planning at POST /v2/cypher/explain. Local servers and Helix Cloud gateways serve the same contracts.

Machine-readable specification

The canonical OpenAPI 3.1 document is published at both predictable URLs:

Use the specification to discover request headers, response codes, health endpoints, query-envelope variants, and example read and write requests. Use the typed SDKs or helix query to build the nested operation tree.

Endpoint

POST /v2/query
Content-Type: application/json

Local development uses http://localhost:6969/v2/query by default. For Helix Cloud, use the gateway URL and database ID shown in the dashboard. The cluster.helix-db.com hostname in the OpenAPI document is a placeholder, not a shared query endpoint. The root OpenAPI server and the /healthz and /readyz operations describe a local HelixDB server. The Helix Cloud gateway is advertised only for POST /v2/query; its separate /health and /readyz contracts are not part of this specification. Local HelixDB accepts encoded request bodies up to 16 MiB. The Helix Cloud gateway accepts up to 2 MiB. Keep requests at or below 2 MiB when the same client must work against both environments. A POST /v2/query body may nest JSON arrays and objects at most 255 levels deep, including under keys the server ignores; a deeper body fails with invalid_query_json.

Authentication

Local servers do not require authentication by default. A Helix Cloud GA shared gateway requires a cluster API key and database ID:

Authorization: Bearer <cluster-api-key>
X-Helix-Database-Id: <database-id>

X-Helix-Tenant-Id remains a legacy alias in GA mode. Database-specific cluster-mode gateway URLs require the API key but reject both database and tenant selection headers. Use the endpoint mode shown in the dashboard; do not copy headers between the two modes. The TypeScript SDK (@helix-db/helix-db 3.2.0 and later) sends X-Helix-Database-Id after client.withDatabaseId("<database-id>"). The published Python, Rust, and Go SDKs do not expose the GA database-selection header; use them with a database-specific cluster gateway URL, or use direct HTTP for a GA shared gateway. Create or rotate the cluster key in the Helix Cloud dashboard. Do not put keys in source control, agent instructions, llms.txt, or catalog manifests. The hosted HelixDB MCP server uses WorkOS OAuth for human sessions and the WorkOS agent registration flow for agents. See the HelixDB MCP guide and the public HelixDB authentication guide.

Request envelope

request_type and the single query variant must agree: read with read, or write with write. query_name is optional diagnostic metadata. Parameters can be untyped, or every parameter can have a matching entry in parameter_types. Read requests can set search_consistency to strong (the default) or eventual; write requests accept only strong. See Search consistency. Raw HTTP JSON supports f32 and f64 parameter declarations. The decoder converts integer JSON values such as 5 and floating-point values such as 5.25 to the declared floating-point type. Values must be finite, and f32 values must fit within the finite f32 range. Floating-point parameters may also be untyped; when parameter_types is present, it must describe every supplied parameter.

{
  "request_type": "read",
  "query_name": "node_count",
  "query": {
    "read": {
      "entries": [
        {
          "query": {
            "name": "node_count",
            "root": {
              "count": {
                "input": {
                  "nodes_where": {
                    "predicate": {
                      "eq": {
                        "left": { "property": "$label" },
                        "right": { "constant": { "string": "User" } }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      ],
      "returns": ["node_count"]
    }
  }
}

Execution headers

Header	Applies to	Purpose
`X-Helix-Warm`	Reads	Warm eligible execution state before normal traffic.
`X-Helix-Require-Writer`	Reads and writes	Reject execution when the selected server is not a writer.
`X-Helix-Await-Durable`	Writes	Flush the writer before returning success.
`X-Helix-Database-Id`	Helix Cloud	Select the managed database behind a gateway.

Boolean execution headers accept true, false, 1, or 0. Warm writes and durability waits on reads are rejected with 400 Bad Request.

Responses

200 returns a JSON object keyed by the requested return variables.
204 means Helix Cloud completed a cache-warming read without a body.
400 reports invalid input or request options. On Helix Cloud, it also reports a missing or malformed authentication header.
401 reports an invalid Helix Cloud API key.
402 reports that Helix Cloud query processing is disabled because credit is exhausted.
403 reports that the Helix Cloud API key lacks permission for the query.
408 reports that a Helix Cloud query exceeded its wall-clock limit.
409 reports a transaction conflict. Retry the whole transaction only when it is idempotent or protected by an application idempotency key.
413 reports that a Helix Cloud request body exceeded 2 MiB. The gateway rejects it before query parsing.
429 reports a Helix Cloud rate limit (rate_limited), which can include Retry-After, or database engine backpressure (index_backpressure): a vector or text index holds its maximum unpublished work, or a strong search lies behind too many unpublished changes or would include more unpublished work than it may. Backpressure responses carry retryable: true and no Retry-After; nothing from the request took effect. See index backpressure.
500 reports an internal query or storage failure.
503 reports that a required writer or ready database is unavailable.

Local servers and Helix Cloud gateways return { "error": "<code>", "msg": "<message>" }. Clients should branch on error and treat msg as diagnostic text. An oversized Cloud request uses payload_too_large as its stable error code. See the query error reference for engine error codes and retry guidance, and Helix Cloud gateway errors for gateway codes.

Cypher

Send a single statement with optional parameters and a query name. The server determines whether the statement reads or modifies data. A Helix Cloud gateway uses that to route reads to readers and writes to the elected writer.

POST /v2/cypher
Content-Type: application/json

{
  "query": "MATCH (n:Person) WHERE n.age >= $age RETURN n.name AS name",
  "parameters": { "age": 30 },
  "query_name": "adults"
}

A successful response has ordered columns and rectangular rows:

{ "columns": ["name"], "rows": [["Ada"], ["Grace"]] }

Each row has one cell per column. Duplicate rows are preserved unless removed by the query, and row order requires ORDER BY. Successful writes without RETURN produce empty columns and rows. Each modifying statement uses one atomic transaction. The authentication and read/write execution headers above apply. A read-only Helix Cloud API key can read and explain, but receives 403 for a modifying statement. Cloud database-selection headers do not select a database on a standalone server. The profile includes fixed-length MATCH and OPTIONAL MATCH, WHERE, WITH, RETURN, UNWIND, aggregation, ordering and windows, and CREATE, property SET/REMOVE, DELETE, and DETACH DELETE. It requires exactly one nonempty label on created nodes and one nonempty type on created relationships. Unlabeled matching is supported. Multiple labels, label changes, and property names beginning with $ are rejected. Assigning null removes a property. Plain node deletion fails if relationships remain; DETACH DELETE removes those relationships. MERGE, variable-length or shortest paths, UNION, subqueries, comprehensions, procedures, schema DDL, temporal/spatial functions, and Bolt are deferred. They produce specific unsupported-feature errors.

Lossless JSON values

Null, booleans, strings, finite floats, lists, and ordinary maps use JSON values. Use these envelopes when plain JSON would lose meaning:

Value	Encoding
Integer outside the JavaScript safe range	`{"$type":"integer","value":"9223372036854775807"}`
Nonfinite float	`{"$type":"float","value":"NaN"}`, `"Infinity"`, or `"-Infinity"`
Literal map containing `$type`	`{"$type":"map","value":{"$type":"user value"}}`
Node	`{"$type":"node","id":"7","labels":["Person"],"properties":{"name":"Ada"}}`
Relationship	`{"$type":"relationship","id":"9","start":"7","end":"8","type":"KNOWS","properties":{}}`
Path	`{"$type":"path","nodes":[...],"relationships":[...]}`

Graph IDs are unsigned decimal strings. id() checks signed 64-bit conversion and reports overflow. Path elements are ordered, while relationship endpoints retain their stored direction. Internal metadata is excluded from property maps. Scalar, list, and map values, including their envelopes, can be supplied as parameters. Graph elements cannot be passed as parameter values.

Cypher errors and planning

Cypher errors include error, msg, and details with a specific detail, phase (compile or runtime), and a nullable UTF-8 byte span. Malformed requests and storage errors retain the native envelope. Resource limits return 429; request/semantic errors return 400; conflicts return 409; internal failures return 500; writer requirements or uncertain commits return 503. An uncertain commit includes retryable:false and must not be retried automatically. The local request and response limits are 16 MiB, with a default 30-second query deadline. An oversized request returns 400 with invalid_request_body. A Helix Cloud gateway accepts request bodies up to 2 MiB and returns 413 with payload_too_large above that. Its query time limit returns 408, and its rate limit applies as for POST /v2/query. Gateway authentication, rate-limit and availability errors use the native envelope. Resource exhaustion returns an error instead of a truncated successful result. Send the same request to POST /v2/cypher/explain to inspect selected access paths, estimated cardinalities, blocking work, Cartesian products, and optimizer budget warnings. This endpoint returns planning data separately from query results and does not execute the statement, including writes. It uses read request options, so X-Helix-Await-Durable:true is invalid.

Next steps

helix query builds and sends requests from JSON or the TypeScript DSL.
Build and run a query explains the operation tree.
Parameters defines typed and untyped runtime values.

Start Here

Core Concepts

Query Guides

HelixDB HTTP API and OpenAPI specification

Machine-readable specification

Endpoint

Authentication

Request envelope

Execution headers

Responses

Cypher

Lossless JSON values

Cypher errors and planning

Next steps

​Machine-readable specification

​Endpoint

​Authentication

​Request envelope

​Execution headers

​Responses

​Cypher

​Lossless JSON values

​Cypher errors and planning

​Next steps

Machine-readable specification

Endpoint

Authentication

Request envelope

Execution headers

Responses

Cypher

Lossless JSON values

Cypher errors and planning

Next steps