robosystems-ai Graph Limits API

openapi: 3.2.0
info:
  title: RoboSystems Graph Limits 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: Graph Limits
  description: 📏 Graph limits - Storage usage, operation limits, and tier configuration
paths:
  /v1/graphs/{graph_id}/limits:
    get:
      tags:
      - Graph Limits
      summary: Get Graph Operational Limits
      description: Limits vary by subscription tier (ladybug-standard, ladybug-large, ladybug-xlarge). Includes storage, query, backup, rate, credit, document, and instance usage limits.
      operationId: getGraphLimits
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: graph_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphLimitsResponse'
        '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'
components:
  schemas:
    DocumentLimits:
      properties:
        current_count:
          type: integer
          title: Current Count
          description: Uploaded documents currently stored for this graph
        max_documents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Documents
          description: Maximum uploaded documents for this tier (null when uncapped)
        approaching_limit:
          type: boolean
          title: Approaching Limit
          description: Whether approaching document limit (>80%)
      type: object
      required:
      - current_count
      - approaching_limit
      title: DocumentLimits
      description: Knowledge-base document usage against the tier's cap.
    StorageItem:
      properties:
        type:
          type: string
          title: Type
          description: 'One of: graph, memory, subgraph, vectors, staging, transient (blue-green build artifact), orphan (a `{parent}_*` database, vector index, or staging file with no row in the graph registry — leftover of a deleted subgraph). Transient and orphan items are collected by the platform''s daily storage-reclaim job.'
        id:
          type: string
          title: Id
          description: Database or index identifier
        bytes:
          type: integer
          title: Bytes
          description: Size in bytes
      type: object
      required:
      - type
      - id
      - bytes
      title: StorageItem
      description: One itemized piece of a graph's on-disk footprint.
    CopyOperationLimits:
      properties:
        max_file_size_gb:
          type: number
          title: Max File Size Gb
          description: Maximum upload file size in GB
        supported_formats:
          items:
            type: string
          type: array
          title: Supported Formats
          description: Supported file formats
      type: object
      required:
      - max_file_size_gb
      - supported_formats
      title: CopyOperationLimits
      description: File upload limits.
    QueryLimits:
      properties:
        max_timeout_seconds:
          type: integer
          title: Max Timeout Seconds
          description: Per-query time ceiling the graph engine enforces, in seconds
        chunk_size:
          type: integer
          title: Chunk Size
          description: Default rows per streamed chunk (a request may set chunk_size, 10-10,000)
        max_rows_per_query:
          type: integer
          title: Max Rows Per Query
          description: Rows a non-streaming Cypher query returns before it stops (the response sets `truncated`); a streamed query returns up to 1,000,000
      type: object
      required:
      - max_timeout_seconds
      - chunk_size
      - max_rows_per_query
      title: QueryLimits
      description: Query operation limits.
    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
    DatabaseStorageEntry:
      properties:
        graph_id:
          type: string
          title: Graph Id
          description: Database identifier
        is_parent:
          type: boolean
          title: Is Parent
          description: Whether this is the parent graph
          default: false
        size_mb:
          anyOf:
          - type: number
          - type: 'null'
          title: Size Mb
          description: Database size in MB
      type: object
      required:
      - graph_id
      title: DatabaseStorageEntry
      description: Storage for a single database on the instance.
    BackupLimits:
      properties:
        backup_retention_days:
          type: integer
          title: Backup Retention Days
          description: Backup retention period in days
        max_backups_per_day:
          type: integer
          title: Max Backups Per Day
          description: Maximum user-initiated backups per day (-1 for unlimited)
        max_downloads_per_month:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Downloads Per Month
          description: Backup downloads allowed per user per calendar month (UTC)
      type: object
      required:
      - backup_retention_days
      - max_backups_per_day
      title: BackupLimits
      description: Backup operation limits.
    StorageLimits:
      properties:
        current_usage_gb:
          anyOf:
          - type: number
          - type: 'null'
          title: Current Usage Gb
          description: Current storage usage in GB
        max_storage_gb:
          type: number
          title: Max Storage Gb
          description: Instance storage cap in GB; ingest and materialize are refused above it
        approaching_limit:
          type: boolean
          title: Approaching Limit
          description: Whether approaching storage limit (>80%)
      type: object
      required:
      - max_storage_gb
      - approaching_limit
      title: StorageLimits
      description: Storage limits information.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SubgraphLimits:
      properties:
        current_count:
          type: integer
          minimum: 0.0
          title: Current Count
          description: Subgraphs currently provisioned under this graph
        max_allowed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Allowed
          description: Maximum subgraphs for this tier (null when uncapped)
        remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Remaining
          description: Subgraphs that can still be created (null when uncapped)
        approaching_limit:
          type: boolean
          title: Approaching Limit
          description: Whether approaching subgraph limit (>80%)
      type: object
      required:
      - current_count
      - approaching_limit
      title: SubgraphLimits
      description: 'Subgraph count against the parent graph tier''s cap.


        Subgraphs are refused at the tier cap regardless of how small they are,

        so this is a count axis independent of the storage one — `instance`

        already itemizes their footprint.'
    GraphLimitsResponse:
      properties:
        graph_id:
          type: string
          title: Graph Id
          description: Graph database identifier
        subscription_tier:
          type: string
          title: Subscription Tier
          description: Rate-limit tier enforced for requests to this graph
        graph_tier:
          type: string
          title: Graph Tier
          description: Graph's database tier
        is_shared_repository:
          type: boolean
          title: Is Shared Repository
          description: Whether this is a shared repository
        storage:
          anyOf:
          - $ref: '#/components/schemas/StorageLimits'
          - type: 'null'
          description: Storage limits and usage (user graphs only)
        queries:
          $ref: '#/components/schemas/QueryLimits'
          description: Query operation limits
        copy_operations:
          anyOf:
          - $ref: '#/components/schemas/CopyOperationLimits'
          - type: 'null'
          description: File upload limits (user graphs only)
        backups:
          anyOf:
          - $ref: '#/components/schemas/BackupLimits'
          - type: 'null'
          description: Backup operation limits (user graphs only)
        rate_limits:
          $ref: '#/components/schemas/RateLimits'
          description: API rate limits
        credits:
          anyOf:
          - $ref: '#/components/schemas/CreditLimits'
          - type: 'null'
          description: AI credit limits (if applicable)
        documents:
          anyOf:
          - $ref: '#/components/schemas/DocumentLimits'
          - type: 'null'
          description: Knowledge-base document usage and tier cap (user graphs only)
        subgraphs:
          anyOf:
          - $ref: '#/components/schemas/SubgraphLimits'
          - type: 'null'
          description: Subgraph count and tier cap (parent user graphs only)
        content:
          anyOf:
          - $ref: '#/components/schemas/ContentLimits'
          - type: 'null'
          description: Per-operation materialization limits (if applicable)
        instance:
          anyOf:
          - $ref: '#/components/schemas/InstanceUsage'
          - type: 'null'
          description: Aggregate instance storage usage (user graphs only)
      type: object
      required:
      - graph_id
      - subscription_tier
      - graph_tier
      - is_shared_repository
      - queries
      - rate_limits
      title: GraphLimitsResponse
      description: Every operational limit that applies to a graph, and its usage.
      examples:
      - backups:
          backup_retention_days: 7
          max_backups_per_day: 2
          max_downloads_per_month: 10
        content:
          chunk_size_rows: 250000
          max_rows_per_copy: 1000000
          max_single_table_rows: 2500000
        copy_operations:
          max_file_size_gb: 0.09765625
          supported_formats:
          - parquet
          - csv
          - json
        credits:
          current_balance: 7500
          monthly_ai_credits: 8000
        documents:
          approaching_limit: false
          current_count: 12
          max_documents: 100
        graph_id: kg1a2b3c4d5
        graph_tier: ladybug-standard
        instance:
          databases:
          - graph_id: kg1a2b3c4d5
            is_parent: true
            size_mb: 2150.0
          - graph_id: kg1a2b3c4d5_dev
            is_parent: false
            size_mb: 360.0
          limit_gb: 20
          node_count: 150000
          status: healthy
          total_storage_gb: 2.45
          usage_percentage: 12.3
        is_shared_repository: false
        queries:
          chunk_size: 500
          max_rows_per_query: 10000
          max_timeout_seconds: 120
        rate_limits:
          burst_capacity: 60
          requests_per_hour: 3600
          requests_per_minute: 60
        storage:
          approaching_limit: false
          current_usage_gb: 2.45
          max_storage_gb: 20
        subgraphs:
          approaching_limit: false
          current_count: 1
          max_allowed: 3
          remaining: 2
        subscription_tier: ladybug-standard
      - graph_id: sec
        graph_tier: ladybug-shared
        is_shared_repository: true
        queries:
          chunk_size: 2500
          max_rows_per_query: 10000
          max_timeout_seconds: 120
        rate_limits:
          burst_capacity: 60
          requests_per_hour: 3600
          requests_per_minute: 60
        subscription_tier: ladybug-standard
    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'
    ContentLimits:
      properties:
        max_rows_per_copy:
          type: integer
          title: Max Rows Per Copy
          description: Maximum rows per copy/materialization operation
        max_single_table_rows:
          type: integer
          title: Max Single Table Rows
          description: Maximum rows per staging table
        chunk_size_rows:
          type: integer
          title: Chunk Size Rows
          description: Rows per materialization chunk
      type: object
      required:
      - max_rows_per_copy
      - max_single_table_rows
      - chunk_size_rows
      title: ContentLimits
      description: Per-operation materialization limits.
    InstanceUsage:
      properties:
        node_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Node Count
          description: Current node count (informational, no limit enforced)
        total_storage_gb:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Storage Gb
          description: Total storage used across all databases in GB
        limit_gb:
          type: number
          title: Limit Gb
          description: Instance storage cap in GB; ingest and materialize are refused above it
        usage_percentage:
          anyOf:
          - type: number
          - type: 'null'
          title: Usage Percentage
          description: Storage usage as percentage of limit (e.g. 105.2). Derived from the enforced figure — durable bytes only, excluding `transient` build artifacts — so it can read lower than total_storage_gb/limit_gb while a blue-green rebuild is in flight.
        status:
          type: string
          title: Status
          description: 'Instance status: ''healthy'' (<80%), ''approaching'' (80-100%), ''over_limit'' (>100%)'
        databases:
          items:
            $ref: '#/components/schemas/DatabaseStorageEntry'
          type: array
          title: Databases
          description: Per-database storage breakdown
        items:
          items:
            $ref: '#/components/schemas/StorageItem'
          type: array
          title: Items
          description: Itemized storage by type — graph, memory, subgraph, vectors, staging, transient, orphan. Sums to total_storage_gb. Only `subgraph` items correspond to live subgraphs, so this is the type to sum when reconciling against the subgraph list.
      type: object
      required:
      - limit_gb
      - status
      title: InstanceUsage
      description: 'Aggregate storage usage across the dedicated instance.


        Covers the parent graph, all subgraphs, DuckDB staging, and vector indexes.'
    RateLimits:
      properties:
        requests_per_minute:
          type: integer
          title: Requests Per Minute
          description: Requests per minute limit
        requests_per_hour:
          type: integer
          title: Requests Per Hour
          description: Requests per hour limit
        burst_capacity:
          type: integer
          title: Burst Capacity
          description: Burst capacity for short spikes
      type: object
      required:
      - requests_per_minute
      - requests_per_hour
      - burst_capacity
      title: RateLimits
      description: API rate limits.
    CreditLimits:
      properties:
        monthly_ai_credits:
          type: integer
          title: Monthly Ai Credits
          description: Monthly AI credits allocation
        current_balance:
          type: integer
          title: Current Balance
          description: Current credit balance
      type: object
      required:
      - monthly_ai_credits
      - current_balance
      title: CreditLimits
      description: AI credit limits (optional).
  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