Operator

Auto-select Operator for Query

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.

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

Path parameters

graph_idstring required

Query parameters

mode'auto' | 'sync' | 'async' | 'stream'

Response modes for execution.

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.

Request body

messagestring required

The query or message to process

contextobject nullable

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

mode'quick' | 'standard' | 'extended' | 'streaming'

Operator execution modes.

operator_typestring nullable

Specific operator type to use (optional)

force_extended_analysisboolean

Force extended analysis mode with comprehensive research

enable_ragboolean

Enable RAG context enrichment

streamboolean

Enable streaming response

max_creditsnumber 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.

Example request

{
  "enable_rag": true,
  "message": "What was Apple's revenue in Q4 2023?"
}

Response

Successful Response

contentstring required

The operator's response content

operator_usedstring required

The operator type that handled the request

mode_used'quick' | 'standard' | 'extended' | 'streaming' required

Operator execution modes.

metadataobject nullable

Response metadata including routing info

tokens_usedobject nullable

Token usage statistics

confidence_scorenumber nullable

Confidence score of the response (0.0-1.0 scale)

operation_idstring nullable

Operation ID for SSE monitoring

is_partialboolean

Whether this is a partial response

error_detailsobject nullable

Error details if any

execution_timenumber nullable

Execution time in seconds

timestampstring date-time

Response timestamp

Example response

{
  "confidence_score": 0.92,
  "content": "Apple's Q4 2023 revenue was $89.5 billion, representing a 1% year-over-year decline. This was driven by strong iPhone sales offset by weakness in the Mac and iPad segments. Services revenue grew 16% to $22.3 billion, continuing its strong growth trajectory.",
  "execution_time": 3.45,
  "metadata": {
    "rag_enrichment": {
      "documents_retrieved": 5,
      "sources": [
        "Apple 10-Q Q4 2023",
        "Earnings Call Transcript Oct 2023"
      ]
    },
    "routing_info": {
      "candidates_evaluated": 3,
      "confidence_scores": {
        "financial": 0.92,
        "rag": 0.23,
        "research": 0.45
      },
      "selection_reason": "Financial query with revenue and metrics keywords"
    }
  },
  "mode_used": "standard",
  "operator_used": "financial",
  "timestamp": "2024-01-15T10:30:45Z",
  "tokens_used": {
    "completion_tokens": 320,
    "prompt_tokens": 450,
    "total_tokens": 770
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.