robosystems-ai Query API
🕸️ Graph queries - Execute Cypher queries on the knowledge graph
🕸️ Graph queries - Execute Cypher queries on the knowledge graph
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/robosystems-ai:robosystems-ai-query-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: RoboSystems Query API
description: 'The REST and GraphQL API for RoboSystems — an open-source, AI-native platform for accounting, financial reporting and investment management. It powers RoboLedger and RoboInvestor.
## Two surfaces
**Platform** — `/v1/…` — graphs, queries, schema, documents, search, memory, connections, billing and access. Reads are REST `GET`s; every write is a named operation at `/operations/{name}` returning an `OperationEnvelope`, accepting an `Idempotency-Key`, and streaming progress at `/v1/operations/{id}/stream`.
→ API reference
**Extensions** — `/extensions/…` — RoboLedger and RoboInvestor, scoped by `graph_id` in the URL. Reads are GraphQL at `POST /extensions/{graph_id}/graphql` and change nothing; writes are named operations at `/extensions/{domain}/{graph_id}/operations/{name}`; analytical views read the materialized graph.
→ Extensions reference · every GraphQL query
## Authenticating
`X-API-Key: rfs…` on REST, GraphQL and per-graph MCP. Browser sessions use JWTs from `POST /v1/auth/login`. The graph-agnostic MCP endpoint `/v1/mcp` takes OAuth 2.1 bearer tokens only.
## Connecting an AI client
Every graph is an MCP server at `POST /v1/graphs/{graph_id}/mcp`, and `POST /v1/mcp` serves OAuth clients that pick their graph at consent.
→ MCP guide
## Clients
`robosystems-client` for Python, `@robosystems/client` for TypeScript.
→ Guides · Technical docs'
version: 1.20.6
tags:
- name: Query
description: 🕸️ Graph queries - Execute Cypher queries on the knowledge graph
paths:
/v1/graphs/{graph_id}/query/cypher:
post:
tags:
- Query
summary: Execute Cypher Statement
description: '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`.'
operationId: executeCypher
security:
- APIKeyHeader: []
- BearerAuth: []
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
title: Graph Id
- name: mode
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/ResponseMode'
- type: 'null'
description: Response mode override
title: Mode
description: Response mode override
- name: chunk_size
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 10000
minimum: 10
- type: 'null'
description: Rows per chunk for streaming
title: Chunk Size
description: Rows per chunk for streaming
- name: test_mode
in: query
required: false
schema:
type: boolean
description: Enable test mode for better debugging
default: false
title: Test Mode
description: Enable test mode for better debugging
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CypherStatementRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'202':
description: Query queued — monitor via SSE at /v1/operations/{operation_id}/stream
'408':
description: Query timeout
'503':
description: Service unavailable
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/graphs/{graph_id}/query/sql:
post:
tags:
- Query
summary: Execute SQL Statement
description: SQL over the graph's columnar tables (DuckDB) — a relational lens on the same graph-centric data, often ahead of the materialized graph. Use `?` placeholders with the `parameters` array to prevent injection. Read-only (SELECT only), 30s timeout, 10,000 row limit. Not available on shared repositories.
operationId: executeSql
security:
- APIKeyHeader: []
- BearerAuth: []
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
title: Graph Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SqlStatementRequest'
description: SQL statement request
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SqlStatementResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'408':
description: Query timeout
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
CypherStatementRequest:
properties:
query:
type: string
maxLength: 50000
minLength: 1
title: Query
description: The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks.
examples:
- 'MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit'
- MATCH (e:Entity)-[r:TRANSACTION]->(t:Entity) WHERE r.amount >= $min_amount AND e.name = $entity_name RETURN e, r, t LIMIT $limit
- MATCH (n:Entity) WHERE n.identifier = $identifier RETURN n
- MATCH (n) RETURN n LIMIT 10
parameters:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Parameters
description: Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation.
examples:
- entity_type: Company
limit: 100
- entity_name: Acme Corp
limit: 50
min_amount: 1000
- identifier: ENT123456
- null
timeout:
anyOf:
- type: integer
maximum: 300.0
minimum: 1.0
- type: 'null'
title: Timeout
description: Query timeout in seconds (1-300)
default: 60
examples:
- 30
- 60
- 120
- 300
additionalProperties: false
type: object
required:
- query
title: CypherStatementRequest
description: Request model for Cypher query execution.
examples:
- parameters:
entity_type: Company
limit: 100
query: 'MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit'
timeout: 60
- parameters:
entity_name: Acme Corp
limit: 50
min_amount: 1000
query: MATCH (e:Entity)-[r:TRANSACTION]->(t:Entity) WHERE r.amount >= $min_amount AND e.name = $entity_name RETURN e, r, t LIMIT $limit
timeout: 120
- parameters:
identifier: ENT123456
query: MATCH (n:Entity) WHERE n.identifier = $identifier RETURN n
timeout: 30
- parameters:
form: 10-K
limit: 20
query: MATCH (c:Company)-[:FILED]->(f:Filing) WHERE f.form_type = $form RETURN c.ticker, c.name, COUNT(f) as filing_count ORDER BY filing_count DESC LIMIT $limit
timeout: 60
- query: MATCH (n) RETURN n LIMIT 10
timeout: 30
ResponseMode:
type: string
enum:
- auto
- sync
- async
- stream
title: ResponseMode
description: Response modes for execution.
SqlStatementResponse:
properties:
columns:
items:
type: string
type: array
title: Columns
description: Column names
rows:
items:
items: {}
type: array
type: array
title: Rows
description: Query results
row_count:
type: integer
title: Row Count
description: Number of rows returned
execution_time_ms:
type: number
title: Execution Time Ms
description: Query execution time
type: object
required:
- columns
- rows
- row_count
- execution_time_ms
title: SqlStatementResponse
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ErrorResponse:
properties:
detail:
type: string
title: Detail
description: Human-readable error message explaining what went wrong
examples:
- Insufficient credits for operation
code:
anyOf:
- type: string
- type: 'null'
title: Code
description: Machine-readable error code for programmatic handling
examples:
- INSUFFICIENT_CREDITS
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Unique request ID for tracking and debugging
examples:
- req_1234567890abcdef
timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Timestamp
description: Timestamp when the error occurred
examples:
- '2024-01-01T00:00:00Z'
type: object
required:
- detail
title: ErrorResponse
description: Error body returned by every endpoint.
example:
code: RESOURCE_NOT_FOUND
detail: Resource not found
request_id: req_1234567890abcdef
timestamp: '2024-01-01T00:00:00Z'
SqlStatementRequest:
properties:
sql:
type: string
title: Sql
description: SQL query over the graph's columnar tables (DuckDB) — a relational lens on the same graph-centric data, often ahead of the materialized graph. Use ? placeholders or $param_name for dynamic values to prevent SQL injection.
examples:
- SELECT * FROM Entity WHERE entity_type = ? LIMIT ?
- SELECT COUNT(*) FROM Transaction WHERE amount > ? AND date >= ?
- SELECT * FROM Entity WHERE industry = $industry LIMIT $limit
- SELECT * FROM Entity LIMIT 10
parameters:
anyOf:
- items: {}
type: array
- additionalProperties: true
type: object
- type: 'null'
title: Parameters
description: Query parameters for safe value substitution. ALWAYS use parameters instead of string concatenation. Pass a list for positional placeholders (`?` or `$1`) and an object for named ones (`$param_name`) — the two forms cannot be mixed in one statement.
examples:
- - Company
- 100
- - 1000
- '2024-01-01'
- industry: Technology
limit: 10
- null
additionalProperties: false
type: object
required:
- sql
title: SqlStatementRequest
examples:
- parameters:
- Company
- 100
sql: SELECT * FROM Entity WHERE entity_type = ? LIMIT ?
- parameters:
- 1000
- '2024-01-01'
sql: SELECT COUNT(*) FROM Transaction WHERE amount > ? AND date >= ?
- sql: SELECT * FROM Entity LIMIT 10
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: API key for authentication
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT bearer token