Execute Cypher Statement
/v1/graphs/{graph_id}/query/cypherPart of Query.
Cypher over the graph (LadybugDB). Main graphs are read-only — use the staging pipeline to ingest data. Subgraphs support full writes. Always use parameterized queries (parameters: {"key": "val"}) to prevent injection. Response modes: auto (default), sync, async, stream. Under load, queries are queued and emit an operation_id for SSE monitoring at /v1/operations/{id}/stream.
Authentication
Authenticate in any one of these ways — not all of them:
- API key in the
X-API-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id |
Query parameters
| Name | Type | Description |
|---|---|---|
modeoptional | ResponseMode | Response mode override One of: |
chunk_sizeoptional | integer | Rows per chunk for streaming |
test_modeoptional | boolean | Enable test mode for better debugging Default: |
Request body
Required, application/json.
| Field | Type | Description |
|---|---|---|
queryrequired | string | The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks. |
parametersoptional | object | Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation. |
timeoutoptional | integer | Query timeout in seconds (1-300) Default: |
Example request
curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"parameters": {
"entity_type": "Company",
"limit": 100
},
"query": "MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit",
"timeout": 60
}'Responses
200 Successful Response
"string"| Status | Meaning |
|---|---|
| 202 | Query queued — monitor via SSE at /v1/operations/{operation_id}/stream |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Access denied |
| 404 | Resource not found |
| 408 | Query timeout |
| 422 | Validation Error |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 503 | Service unavailable |