robosystems-ai Service Offerings API

openapi: 3.2.0
info:
  title: RoboSystems Service Offerings 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: Service Offerings
  description: 🛍️ Service offerings - View available offers and pricing
paths:
  /v1/offering:
    get:
      tags:
      - Service Offerings
      summary: Get Service Offerings
      description: Returns all subscription tiers, shared repository plans, and AI credit costs. No authentication required.
      operationId: getServiceOfferings
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOfferingsResponse'
        '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'
components:
  schemas:
    GraphSubscriptionTier:
      properties:
        name:
          type: string
          title: Name
          description: Infrastructure tier identifier (e.g., ladybug-standard)
        display_name:
          type: string
          title: Display Name
          description: Display name for UI
        description:
          type: string
          title: Description
          description: Tier description
        monthly_price_per_graph:
          type: number
          title: Monthly Price Per Graph
          description: Monthly price in USD per graph
        monthly_credits_per_graph:
          type: integer
          title: Monthly Credits Per Graph
          description: Monthly AI credits per graph
        infrastructure:
          type: string
          title: Infrastructure
          description: Infrastructure description
        features:
          items:
            type: string
          type: array
          title: Features
          description: List of features
        backup_retention_days:
          type: integer
          title: Backup Retention Days
          description: Backup retention in days
        priority_support:
          type: boolean
          title: Priority Support
          description: Whether priority support is included
        max_subgraphs:
          type: integer
          title: Max Subgraphs
          description: Maximum subgraphs supported
          default: 0
        api_rate_multiplier:
          type: number
          title: Api Rate Multiplier
          description: API rate multiplier
        backend:
          type: string
          title: Backend
          description: Database backend identifier
        instance_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Type
          description: Instance type
        instance_storage_limit_gb:
          type: number
          title: Instance Storage Limit Gb
          description: Instance storage cap in GB; ingest and materialize are refused above it
          default: 0
      type: object
      required:
      - name
      - display_name
      - description
      - monthly_price_per_graph
      - monthly_credits_per_graph
      - infrastructure
      - features
      - backup_retention_days
      - priority_support
      - api_rate_multiplier
      - backend
      title: GraphSubscriptionTier
      description: 'Information about a graph infrastructure tier.


        Each tier represents a per-graph subscription option with specific

        infrastructure, performance, and pricing characteristics.'
    GraphSubscriptions:
      properties:
        description:
          type: string
          title: Description
          description: Description of graph subscriptions
        pricing_model:
          type: string
          title: Pricing Model
          description: Pricing model type (per_graph or per_organization)
        tiers:
          items:
            $ref: '#/components/schemas/GraphSubscriptionTier'
          type: array
          title: Tiers
          description: Available infrastructure tiers
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Important notes
      type: object
      required:
      - description
      - pricing_model
      - tiers
      - notes
      title: GraphSubscriptions
      description: 'Graph subscription offerings.


        Graph subscriptions are per-graph, not per-organization. Each graph

        created by an organization has its own subscription with its own

        infrastructure tier, pricing, and credit allocation.'
    TokenPricing:
      properties:
        input_per_1k_tokens:
          type: number
          title: Input Per 1K Tokens
          description: Credits per 1K input tokens
        output_per_1k_tokens:
          type: number
          title: Output Per 1K Tokens
          description: Credits per 1K output tokens
      type: object
      required:
      - input_per_1k_tokens
      - output_per_1k_tokens
      title: TokenPricing
      description: AI token pricing for a specific model.
    RepositorySubscriptions:
      properties:
        description:
          type: string
          title: Description
          description: Description of repository subscriptions
        pricing_model:
          type: string
          title: Pricing Model
          description: Pricing model type (per_graph or per_organization)
        repositories:
          items:
            $ref: '#/components/schemas/RepositoryInfo'
          type: array
          title: Repositories
          description: Available repositories
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Important notes
      type: object
      required:
      - description
      - pricing_model
      - repositories
      - notes
      title: RepositorySubscriptions
      description: 'Repository subscription offerings.


        Repository subscriptions are per-organization, not per-graph. All members

        of an organization share access to subscribed repositories.'
    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'
    ServiceOfferingsResponse:
      properties:
        billing_enabled:
          type: boolean
          title: Billing Enabled
          description: Whether billing and payments are enabled
        graph_subscriptions:
          $ref: '#/components/schemas/GraphSubscriptions'
          description: Graph subscription offerings
        repository_subscriptions:
          $ref: '#/components/schemas/RepositorySubscriptions'
          description: Repository subscription offerings
        operation_costs:
          $ref: '#/components/schemas/OperationCosts'
          description: Operation cost information
        summary:
          $ref: '#/components/schemas/ServiceOfferingSummary'
          description: Summary information
      type: object
      required:
      - billing_enabled
      - graph_subscriptions
      - repository_subscriptions
      - operation_costs
      - summary
      title: ServiceOfferingsResponse
      description: Complete service offerings response.
    OfferingRepositoryPlan:
      properties:
        plan:
          type: string
          title: Plan
          description: Plan identifier
        name:
          type: string
          title: Name
          description: Plan name
        monthly_price:
          type: number
          title: Monthly Price
          description: Monthly price in USD
        monthly_credits:
          type: integer
          title: Monthly Credits
          description: Monthly credit allocation
        access_level:
          type: string
          title: Access Level
          description: Access level
        features:
          items:
            type: string
          type: array
          title: Features
          description: List of features
        rate_limits:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: integer
              - type: 'null'
            type: object
          - type: 'null'
          title: Rate Limits
          description: Rate limits for this plan
      type: object
      required:
      - plan
      - name
      - monthly_price
      - monthly_credits
      - access_level
      - features
      title: OfferingRepositoryPlan
      description: Information about a repository plan.
    OperationCosts:
      properties:
        description:
          type: string
          title: Description
          description: Description of operation costs
        ai_operations:
          additionalProperties:
            type: number
          type: object
          title: Ai Operations
          description: Base costs for AI operations
        token_pricing:
          additionalProperties:
            $ref: '#/components/schemas/TokenPricing'
          type: object
          title: Token Pricing
          description: Token pricing by model
        included_operations:
          items:
            type: string
          type: array
          title: Included Operations
          description: Operations that don't consume credits
        notes:
          items:
            type: string
          type: array
          title: Notes
          description: Important notes about costs
      type: object
      required:
      - description
      - ai_operations
      - token_pricing
      - included_operations
      - notes
      title: OperationCosts
      description: Operation cost information.
    RepositoryInfo:
      properties:
        type:
          type: string
          title: Type
          description: Repository type identifier
        name:
          type: string
          title: Name
          description: Repository name
        description:
          type: string
          title: Description
          description: Repository description
        enabled:
          type: boolean
          title: Enabled
          description: Whether repository is enabled
        coming_soon:
          type: boolean
          title: Coming Soon
          description: Whether repository is coming soon
        plans:
          items:
            $ref: '#/components/schemas/OfferingRepositoryPlan'
          type: array
          title: Plans
          description: Available plans
      type: object
      required:
      - type
      - name
      - description
      - enabled
      - coming_soon
      - plans
      title: RepositoryInfo
      description: Information about a shared repository.
    ServiceOfferingSummary:
      properties:
        total_graph_tiers:
          type: integer
          title: Total Graph Tiers
          description: Total number of graph tiers
        total_repositories:
          type: integer
          title: Total Repositories
          description: Total number of repositories
        enabled_repositories:
          type: integer
          title: Enabled Repositories
          description: Number of enabled repositories
        coming_soon_repositories:
          type: integer
          title: Coming Soon Repositories
          description: Number of coming soon repositories
      type: object
      required:
      - total_graph_tiers
      - total_repositories
      - enabled_repositories
      - coming_soon_repositories
      title: ServiceOfferingSummary
      description: Summary of service offerings.
  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