robosystems-ai Operator API

openapi: 3.2.0
info:
  title: RoboSystems Operator 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: Operator
  description: 🤖 AI Operators - AI agent orchestration and execution
paths:
  /v1/graphs/{graph_id}/operator:
    get:
      tags:
      - Operator
      summary: List Available Operators
      description: Filter by capability using the `capability` query param (e.g., `financial_analysis`, `rag_search`).
      operationId: listOperators
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: graph_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Id
      - name: capability
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by capability (e.g., 'financial_analysis', 'rag_search')
          title: Capability
        description: Filter by capability (e.g., 'financial_analysis', 'rag_search')
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorListResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Operator
      summary: Auto-select Operator for Query
      description: '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.'
      operationId: autoSelectOperator
      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: '`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.'
          title: Mode
        description: '`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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperatorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorResponse'
        '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: Run queued on the worker — follow `_links.stream`
        '402':
          description: Insufficient credits
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/graphs/{graph_id}/operator/{operator_type}:
    get:
      tags:
      - Operator
      summary: Get Operator Metadata
      operationId: getOperatorMetadata
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: graph_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Id
      - name: operator_type
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9_]{2,32}$
          description: Operator type identifier (e.g., 'analyst', 'mapping')
          title: Operator Type
        description: Operator type identifier (e.g., 'analyst', 'mapping')
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorMetadataResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Operator
      summary: Execute Specific Operator
      description: '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.'
      operationId: executeSpecificOperator
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: operator_type
        in: path
        required: true
        schema:
          type: string
          title: Operator Type
      - 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: '`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.'
          title: Mode
        description: '`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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperatorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorResponse'
        '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: Run queued on the worker — follow `_links.stream`
        '402':
          description: Insufficient credits
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OperatorResponse:
      properties:
        content:
          type: string
          title: Content
          description: The operator's response content
        operator_used:
          type: string
          title: Operator Used
          description: The operator type that handled the request
        mode_used:
          $ref: '#/components/schemas/OperatorMode'
          description: The execution mode used
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Response metadata including routing info
        tokens_used:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Tokens Used
          description: Token usage statistics
        confidence_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence Score
          description: Confidence score of the response (0.0-1.0 scale)
        operation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Operation Id
          description: Operation ID for SSE monitoring
        is_partial:
          type: boolean
          title: Is Partial
          description: Whether this is a partial response
          default: false
        error_details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Error Details
          description: Error details if any
        execution_time:
          anyOf:
          - type: number
          - type: 'null'
          title: Execution Time
          description: Execution time in seconds
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Response timestamp
      type: object
      required:
      - content
      - operator_used
      - mode_used
      title: OperatorResponse
      description: Response model for operator interactions.
      examples:
      - 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
      - confidence_score: 0.88
        content: 'The cloud computing market is dominated by three major players: AWS (32% market share), Microsoft Azure (23%), and Google Cloud (10%). Over the past year, growth rates have been: AWS 12%, Azure 27%, Google Cloud 28%. The market shows clear consolidation trends...'
        execution_time: 12.3
        metadata:
          analysis_depth: comprehensive
          routing_info:
            candidates_evaluated: 3
            selection_reason: Market research query requiring comprehensive analysis
          sources_consulted: 15
        mode_used: extended
        operator_used: research
        timestamp: '2024-01-15T10:35:22Z'
        tokens_used:
          completion_tokens: 850
          prompt_tokens: 1200
          total_tokens: 2050
    ResponseMode:
      type: string
      enum:
      - auto
      - sync
      - async
      - stream
      title: ResponseMode
      description: Response modes for execution.
    OperatorMetadataResponse:
      properties:
        name:
          type: string
          title: Name
          description: Operator name
        description:
          type: string
          title: Description
          description: Operator description
        version:
          type: string
          title: Version
          description: Operator version
        capabilities:
          items:
            type: string
          type: array
          title: Capabilities
          description: Operator capabilities
        supported_modes:
          items:
            type: string
          type: array
          title: Supported Modes
          description: Supported execution modes
        requires_credits:
          type: boolean
          title: Requires Credits
          description: Whether operator requires credits
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
          description: Operator author
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Operator tags
      type: object
      required:
      - name
      - description
      - version
      - capabilities
      - supported_modes
      - requires_credits
      title: OperatorMetadataResponse
      description: Response for operator metadata.
    OperatorListResponse:
      properties:
        operators:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Operators
          description: Dictionary of available operators with metadata
        total:
          type: integer
          title: Total
          description: Total number of operators
      type: object
      required:
      - operators
      - total
      title: OperatorListResponse
      description: Response for listing available operators.
    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'
    OperatorMessage:
      properties:
        role:
          type: string
          title: Role
          description: Message role (user/assistant)
        content:
          type: string
          maxLength: 100000
          title: Content
          description: Message content
        timestamp:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Timestamp
          description: Message timestamp
      type: object
      required:
      - role
      - content
      title: OperatorMessage
      description: Message in conversation history.
    SelectionCriteria:
      properties:
        min_confidence:
          type: number
          title: Min Confidence
          description: Minimum confidence score
          default: 0.3
        required_capabilities:
          items:
            type: string
          type: array
          title: Required Capabilities
          description: Required operator capabilities
        preferred_mode:
          anyOf:
          - $ref: '#/components/schemas/OperatorMode'
          - type: 'null'
          description: Preferred execution mode
        max_response_time:
          type: number
          title: Max Response Time
          description: Maximum response time in seconds
          default: 60.0
        excluded_operators:
          items:
            type: string
          type: array
          title: Excluded Operators
          description: Operators to exclude from selection
      type: object
      title: SelectionCriteria
      description: Criteria for operator selection.
    OperatorRequest:
      properties:
        message:
          type: string
          maxLength: 100000
          minLength: 1
          title: Message
          description: The query or message to process
        history:
          items:
            $ref: '#/components/schemas/OperatorMessage'
          type: array
          maxItems: 100
          title: History
          description: Conversation history. Omit it on a threaded request and the run is seeded from the thread's own record instead
        thread_id:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^[A-Za-z0-9_-]+$
          - type: 'null'
          title: Thread Id
          description: Groups this run with the earlier runs of one conversation. A caller mints the id (any ULID or UUID) on the first question and sends it with each follow-up; the run is recorded under it, and with no `history` given, the thread's last exchanges are the history. Runs list by thread at `GET /v1/graphs/{graph_id}/audit/runs`
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
          description: Additional context for analysis (e.g., enable_rag, include_schema)
        mode:
          anyOf:
          - $ref: '#/components/schemas/OperatorMode'
          - type: 'null'
          description: Execution mode
          default: standard
        operator_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Operator Type
          description: Specific operator type to use (optional)
        selection_criteria:
          anyOf:
          - $ref: '#/components/schemas/SelectionCriteria'
          - type: 'null'
          description: Criteria for operator selection
        force_extended_analysis:
          type: boolean
          title: Force Extended Analysis
          description: Force extended analysis mode with comprehensive research
          default: false
        enable_rag:
          type: boolean
          title: Enable Rag
          description: Enable RAG context enrichment
          default: true
        stream:
          type: boolean
          title: Stream
          description: Enable streaming response
          default: false
        max_credits:
          anyOf:
          - type: number
            maximum: 100000.0
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Max Credits
          description: 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.
      type: object
      required:
      - message
      title: OperatorRequest
      description: Request model for operator interactions.
      examples:
      - enable_rag: true
        message: What was Apple's revenue in Q4 2023?
      - 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?
      - 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.0
          min_confidence: 0.7
          preferred_mode: extended
          required_capabilities:
          - financial_analysis
          - market_research
    OperatorMode:
      type: string
      enum:
      - quick
      - standard
      - extended
      - streaming
      title: OperatorMode
      description: Operator execution modes.
  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