Execute Specific Operator

post/v1/graphs/{graph_id}/operator/{operator_type}

Available: analyst (natural-language questions over the graph — curated financial reads, documents, memory, and read-only Cypher; RAG retrieval is one of its capabilities, not a separate operator; cypher is accepted as its former name) and mapping (Chart of Accounts → rs-gaap mapping, roboledger graphs only). GET /v1/graphs/{graph_id}/operator lists what is registered. 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
`operator_type`required	string	Operator Type
`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

Constraints: 1–100000 characters

historyoptional

OperatorMessage[]

Conversation history

Constraints: at most 100 items

OperatorMessage fields

Field Type Description

rolerequired

string

Message role (user/assistant)

contentrequired

string

Message content

Constraints: at most 100000 characters

timestampoptional

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.

Constraints: at most 100000; greater than 0

Example request

curl · example 1 of 3

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operator/{operator_type}" \
  -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?"
}'

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operator/{operator_type}" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enable_rag": true,
  "history": [
    {
      "content": "What was Apple'\''s revenue in Q4 2023?",
      "role": "user"
    },
    {
      "content": "Apple'\''s Q4 2023 revenue was $89.5 billion, representing a 1% year-over-year decline.",
      "role": "assistant"
    }
  ],
  "message": "How did that compare to the previous quarter?"
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operator/{operator_type}" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "context": {
    "focus_areas": [
      "market_share",
      "growth_trends"
    ],
    "industry": "technology",
    "time_period": "2023-2024"
  },
  "enable_rag": true,
  "force_extended_analysis": true,
  "message": "Analyze the competitive landscape in cloud computing, focusing on market share and growth trends",
  "mode": "extended",
  "selection_criteria": {
    "max_response_time": 45,
    "min_confidence": 0.7,
    "preferred_mode": "extended",
    "required_capabilities": [
      "financial_analysis",
      "market_research"
    ]
  }
}'

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