---
title: "Auto-select Operator for Query"
method: POST
path: "/v1/graphs/{graph_id}/operator"
tags: ["Operator"]
---

# Auto-select Operator for Query

`POST /v1/graphs/{graph_id}/operator`

## 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/v1/graphs/{graph_id}/operator`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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.

## Path parameters

- `graph_id` string, required

## Query parameters

- `mode` 'auto' | 'sync' | 'async' | 'stream': Response modes for execution.

## Request body

- OperatorRequest: Request model for operator interactions.
  - `message` string, required: The query or message to process
  - `history` OperatorMessage[]: Conversation history
    - `role` string, required: Message role (user/assistant)
    - `content` string, required: Message content
    - `timestamp` string, date-time, nullable: Message timestamp
  - `context` object, nullable: Additional context for analysis (e.g., enable_rag, include_schema)
  - `mode` 'quick' | 'standard' | 'extended' | 'streaming': Operator execution modes.
  - `operator_type` string, nullable: Specific operator type to use (optional)
  - `selection_criteria` SelectionCriteria: Criteria for operator selection.
    - `min_confidence` number: Minimum confidence score
    - `required_capabilities` string[]: Required operator capabilities
    - `preferred_mode` 'quick' | 'standard' | 'extended' | 'streaming': Operator execution modes.
    - `max_response_time` number: Maximum response time in seconds
    - `excluded_operators` string[]: Operators to exclude from selection
  - `force_extended_analysis` boolean: Force extended analysis mode with comprehensive research
  - `enable_rag` boolean: Enable RAG context enrichment
  - `stream` boolean: Enable streaming response
  - `max_credits` number, nullable: 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.

## Response `200`

Successful Response

- OperatorResponse: Response model for operator interactions.
  - `content` string, required: The operator's response content
  - `operator_used` string, required: The operator type that handled the request
  - `mode_used` 'quick' | 'standard' | 'extended' | 'streaming', required: Operator execution modes.
  - `metadata` object, nullable: Response metadata including routing info
  - `tokens_used` object, nullable: Token usage statistics
  - `confidence_score` number, nullable: Confidence score of the response (0.0-1.0 scale)
  - `operation_id` string, nullable: Operation ID for SSE monitoring
  - `is_partial` boolean: Whether this is a partial response
  - `error_details` object, nullable: Error details if any
  - `execution_time` number, nullable: Execution time in seconds
  - `timestamp` string, date-time: Response timestamp

## Other responses

- `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

---

[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)