robosystems-ai Backup API

openapi: 3.2.0
info:
  title: RoboSystems Backup 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: Backup
  description: 💾 Backup - List, download, and inspect graph backups
paths:
  /v1/graphs/{graph_id}/backups:
    get:
      tags:
      - Backup
      summary: List graph database backups
      operationId: listBackups
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: graph_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of backups to return
          default: 50
          title: Limit
        description: Maximum number of backups to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of backups to skip
          default: 0
          title: Offset
        description: Number of backups to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupListResponse'
        '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'
  /v1/graphs/{graph_id}/backups/{backup_id}/download:
    get:
      tags:
      - Backup
      summary: Get temporary download URL for backup
      description: 'Generate a temporary download URL for a backup. The filename carries the extension listed as `download_extension` on the backup: `.lbdb.zip` is a ZIP holding the LadybugDB database file `{graph_id}.lbdb`; `.lbdb.zst` (shared repository snapshots) is a single zstd-compressed database file; decompress it with `zstd -d`.'
      operationId: getBackupDownloadUrl
      security:
      - APIKeyHeader: []
      - BearerAuth: []
      parameters:
      - name: backup_id
        in: path
        required: true
        schema:
          type: string
          description: Backup identifier
          title: Backup Id
        description: Backup identifier
      - name: graph_id
        in: path
        required: true
        schema:
          type: string
          title: Graph Id
      - name: expires_in
        in: query
        required: false
        schema:
          type: integer
          maximum: 86400
          minimum: 300
          description: URL expiration time in seconds
          default: 3600
          title: Expires In
        description: URL expiration time in seconds
      responses:
        '200':
          description: Download URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupDownloadUrlResponse'
        '403':
          description: Access denied — admin role on the graph, or an eligible repository subscription, is required
        '404':
          description: Backup not found
        '500':
          description: Failed to generate download URL
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/graphs/{graph_id}/backups/stats:
    get:
      tags:
      - Backup
      summary: Get backup statistics
      operationId: getBackupStats
      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/BackupStatsResponse'
        '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:
    BackupStatsResponse:
      properties:
        graph_id:
          type: string
          title: Graph Id
        total_backups:
          type: integer
          title: Total Backups
        successful_backups:
          type: integer
          title: Successful Backups
        failed_backups:
          type: integer
          title: Failed Backups
        success_rate:
          type: number
          title: Success Rate
        total_original_size_bytes:
          type: integer
          title: Total Original Size Bytes
        total_compressed_size_bytes:
          type: integer
          title: Total Compressed Size Bytes
        storage_saved_bytes:
          type: integer
          title: Storage Saved Bytes
        average_compression_ratio:
          type: number
          title: Average Compression Ratio
        latest_backup_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Backup Date
        backup_formats:
          additionalProperties:
            type: integer
          type: object
          title: Backup Formats
      type: object
      required:
      - graph_id
      - total_backups
      - successful_backups
      - failed_backups
      - success_rate
      - total_original_size_bytes
      - total_compressed_size_bytes
      - storage_saved_bytes
      - average_compression_ratio
      - latest_backup_date
      - backup_formats
      title: BackupStatsResponse
      description: Response model for backup statistics.
    DownloadQuota:
      properties:
        limit_per_month:
          type: integer
          title: Limit Per Month
          description: Maximum downloads allowed per month
        used_this_month:
          type: integer
          title: Used This Month
          description: Number of downloads used this month
        remaining:
          type: integer
          title: Remaining
          description: Downloads remaining this month
        resets_at:
          type: string
          format: date-time
          title: Resets At
          description: When the monthly limit resets (UTC)
      type: object
      required:
      - limit_per_month
      - used_this_month
      - remaining
      - resets_at
      title: DownloadQuota
      description: Download quota information for shared repository backups.
    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
    BackupListResponse:
      properties:
        backups:
          items:
            $ref: '#/components/schemas/BackupResponse'
          type: array
          title: Backups
        total_count:
          type: integer
          title: Total Count
        graph_id:
          type: string
          title: Graph Id
        is_shared_repository:
          type: boolean
          title: Is Shared Repository
          description: Whether this is a shared repository (limits apply)
          default: false
        download_quota:
          anyOf:
          - $ref: '#/components/schemas/DownloadQuota'
          - type: 'null'
          description: Download quota for shared repositories
      type: object
      required:
      - backups
      - total_count
      - graph_id
      title: BackupListResponse
      description: Response model for backup list.
    BackupDownloadUrlResponse:
      properties:
        download_url:
          type: string
          title: Download Url
          description: Pre-signed S3 URL for downloading the backup file
          examples:
          - https://s3.amazonaws.com/robosystems-backups/kg1a2b3c4d5/backup.lbdb.tar.gz?X-Amz-Credential=...
        expires_in:
          type: integer
          maximum: 86400.0
          minimum: 300.0
          title: Expires In
          description: URL expiration time in seconds from now
          examples:
          - 3600
        expires_at:
          type: number
          title: Expires At
          description: Unix timestamp when the URL expires
          examples:
          - 1705315200.0
        backup_id:
          type: string
          title: Backup Id
          description: Backup identifier
          examples:
          - bk1a2b3c4d5
        graph_id:
          type: string
          title: Graph Id
          description: Graph database identifier
          examples:
          - kg1a2b3c4d5
      type: object
      required:
      - download_url
      - expires_in
      - expires_at
      - backup_id
      - graph_id
      title: BackupDownloadUrlResponse
      description: Response model for backup download URL generation.
      examples:
      - backup_id: bk1a2b3c4d5
        download_url: https://s3.amazonaws.com/robosystems-user-prod/graph-backups/databases/kg1a2b3c4d5/full/backup-20240115_100000.lbdb.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
        expires_at: 1705315200.0
        expires_in: 3600
        graph_id: kg1a2b3c4d5
      - backup_id: bk9f8e7d6c5
        download_url: https://s3.amazonaws.com/robosystems-user-prod/graph-backups/databases/kg9f8e7d6c5/full/backup-20240114_183000.lbdb.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
        expires_at: 1705401600.0
        expires_in: 86400
        graph_id: kg9f8e7d6c5
      - backup_id: bksec123456
        download_url: https://account.r2.cloudflarestorage.com/robosystems-downloads/downloads/sec/sec.lbdb.zst?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
        expires_at: 1705314900.0
        expires_in: 300
        graph_id: sec
    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'
    BackupResponse:
      properties:
        backup_id:
          type: string
          title: Backup Id
        graph_id:
          type: string
          title: Graph Id
        backup_format:
          type: string
          title: Backup Format
        backup_type:
          type: string
          title: Backup Type
        initiated_by:
          type: string
          title: Initiated By
          description: Who started this backup. 'user' is one you requested and it counts against the tier's daily backup limit; 'scheduled' is taken nightly on your behalf and does not; 'final' is the copy taken when a graph is deprovisioned, so you can still retrieve your data afterwards.
          default: user
        memory_included:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Memory Included
          description: Whether the archive carries this graph's semantic memory store. Null for backups taken before memory was included, which make no claim either way — distinct from false, which means the graph had none.
        status:
          type: string
          title: Status
        original_size_bytes:
          type: integer
          title: Original Size Bytes
        compressed_size_bytes:
          type: integer
          title: Compressed Size Bytes
        compression_ratio:
          type: number
          title: Compression Ratio
        node_count:
          type: integer
          title: Node Count
        relationship_count:
          type: integer
          title: Relationship Count
        backup_duration_seconds:
          type: number
          title: Backup Duration Seconds
        compression_enabled:
          type: boolean
          title: Compression Enabled
        download_extension:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Extension
          description: 'Extension the download will carry, and therefore how to unpack it: ''.lbdb.zip'' is a ZIP holding the LadybugDB database file, ''.lbdb.zst'' is zstd-compressed (`zstd -d`). Null only when the backup has no stored object yet.'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
      type: object
      required:
      - backup_id
      - graph_id
      - backup_format
      - backup_type
      - status
      - original_size_bytes
      - compressed_size_bytes
      - compression_ratio
      - node_count
      - relationship_count
      - backup_duration_seconds
      - compression_enabled
      - created_at
      - completed_at
      - expires_at
      title: BackupResponse
      description: Response model for backup information.
  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