Auto-select Operator for Query

post/v1/graphs/{graph_id}/operator

Routes to the best operator for your query. Operators: analyst (answers natural-language questions over the graph — curated financial reads, documents, memory, and read-only Cypher; supports quick, standard, extended; cypher is accepted as its former name) and mapping (autonomous Chart of Accounts → rs-gaap mapping; roboledger graphs only, extended only). GET /v1/graphs/{graph_id}/operator lists what is registered. Credits are consumed by actual token usage, not a fixed price per mode. The run executes on the background worker: the default answer is 202 with the operation's _links (stream, status, cancel); ?mode=sync waits up to 50s and answers 200 with the result.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Query parameters

Name	Type	Description
`mode`optional	ResponseMode	`sync` waits up to 50s for the answer and returns 200 with it (202 with the operation links if the worker is still busy). Anything else — `async`, `stream`, `auto` or unset — queues the run and returns 202; follow `_links.stream` for progress and the result. One of: `auto`, `sync`, `async`, `stream`

Request body

Required, application/json.

Field Type Description

messagerequired

string

The query or message to process

historyoptional

OperatorMessage[]

Conversation history

OperatorMessage fields

Field	Type	Description
`role`required	string	Message role (user/assistant)
`content`required	string	Message content
`timestamp`optional	string (date-time)	Message timestamp

contextoptional

object

Additional context for analysis (e.g., enable_rag, include_schema)

modeoptional

OperatorMode

Execution mode

One of: quick, standard, extended, streaming

Default: standard

operator_typeoptional

string

Specific operator type to use (optional)

selection_criteriaoptional

SelectionCriteria

Criteria for operator selection

SelectionCriteria fields

Field	Type	Description
`min_confidence`optional	number	Minimum confidence score Default: `0.3`
`required_capabilities`optional	string[]	Required operator capabilities
`preferred_mode`optional	OperatorMode	Preferred execution mode One of: `quick`, `standard`, `extended`, `streaming`
`max_response_time`optional	number	Maximum response time in seconds Default: `60`
`excluded_operators`optional	string[]	Operators to exclude from selection

force_extended_analysisoptional

boolean

Force extended analysis mode with comprehensive research

Default: false

enable_ragoptional

boolean

Enable RAG context enrichment

Default: true

streamoptional

boolean

Enable streaming response

Default: false

max_creditsoptional

number

Per-question credit ceiling. Once the run's consumed credits reach this number, no further tool step starts and the operator answers from what it has (the wrap-up itself may carry the total slightly past the ceiling). Omit for the mode's default step-bounded behavior.

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operator" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enable_rag": true,
  "message": "What was Apple'\''s revenue in Q4 2023?"
}'

Responses

200 Successful Response

Field	Type	Description
`content`required	string	The operator's response content
`operator_used`required	string	The operator type that handled the request
`mode_used`required	OperatorMode	The execution mode used One of: `quick`, `standard`, `extended`, `streaming`
`metadata`optional	object	Response metadata including routing info
`tokens_used`optional	object	Token usage statistics
`confidence_score`optional	number	Confidence score of the response (0.0-1.0 scale)
`operation_id`optional	string	Operation ID for SSE monitoring
`is_partial`optional	boolean	Whether this is a partial response Default: `false`
`error_details`optional	object	Error details if any
`execution_time`optional	number	Execution time in seconds
`timestamp`optional	string (date-time)	Response timestamp

Status	Meaning
202	Run queued on the worker — follow `_links.stream`
400	Invalid request
401	Authentication required
402	Insufficient credits
403	Access denied
404	Resource not found
422	Validation Error
429	Rate limit exceeded
500	Internal server error