HelixDB HTTP API and OpenAPI specification

For the complete documentation index optimized for AI agents, see llms.txt.

​

Machine-readable specification

• https://www.helix-db.com/openapi.json
• https://docs.helix-db.com/openapi.json

​

Endpoint

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

​

Authentication

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

​

Request envelope

{
  "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

​

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 and can include Retry-After.
• 500 reports an internal query or storage failure.
• 503 reports that a required writer or ready database is unavailable.

​

Related resources

• 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.