---
title: "Run a GraphQL query"
method: POST
path: "/extensions/{graph_id}/graphql"
tags: ["GraphQL"]
---

# Run a GraphQL query

`POST /extensions/{graph_id}/graphql`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/{graph_id}/graphql`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The typed read surface for a graph's extensions data — RoboLedger and RoboInvestor records as they stand right now. Writes are not here: they are the named operations at `POST /extensions/{domain}/{graph_id}/operations/{name}`.

Send a standard GraphQL POST body: a `query` document, with optional `variables` and `operationName`.

Queries are scoped by the URL: `graph_id` is a path parameter and never a query argument, so a document cannot name a graph that disagrees with the path it was sent to. Reads hit the operational (OLTP) extensions database, so they reflect the books as they stand now; the analytical projection is Cypher at `POST /v1/graphs/{graph_id}/query/cypher`.

The schema is composed per deployment: ledger fields require RoboLedger and investor fields require RoboInvestor, and a disabled domain is absent from introspection rather than failing at runtime. Every field carries a description, so introspection is the authoritative, deployment-specific reference.

**Auth**: pass `X-API-Key` (or a JWT `Authorization: Bearer` header). Unauthenticated introspection queries are deliberately allowed for SDK codegen; data queries require credentials and raise `UNAUTHENTICATED`.

**Error codes**: `LEDGER_NOT_INITIALIZED`, `INVESTOR_NOT_INITIALIZED`, and `UNAUTHENTICATED` surface in the GraphQL `errors[].extensions.code` field. GraphQL reports errors with HTTP 200 and a populated `errors[]`, so check that array rather than the status code.

## Path parameters

- `graph_id` string, required

## Request body

- object
  - `query` string, required: The GraphQL document to execute.
  - `variables` object: Values for the document's variables.
  - `operationName` string: Which operation to run, when the document declares more than one.

## Response `200`

Successful Response

- unknown

## Other responses

- `401`: Unauthorized — credentials presented but invalid
- `403`: Forbidden — caller cannot access this graph
- `422`: Validation Error
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)