Flowra Sandbox API

openapi: 3.2.0
info:
  title: Flowra API (API Key Endpoints) Sandbox API
  description: '**Flowra** is an AI-powered platform for building agents, workflows, and integrations.


    ### Capabilities

    - **Tools & Toolkits** – Define and group tools for agents and workflows.

    - **Workflows** – Orchestrate steps and automate processes.

    - **Triggers** – Schedule or event-based execution.

    - **Auth & Connections** – OAuth, API keys, and connected accounts.

    - **MCP** – Model Context Protocol server integration.

    - **Knowledge / RAG** – Add files and URLs for retrieval-augmented generation.


    ### Authentication

    Use the **x-api-key** header with a project API key to access endpoints that support API Key auth. Create and manage API keys in the dashboard under your project settings.


    Only endpoints that support API Key authentication via the @ApiKeyEnabled() decorator.


    Send x-api-key (required). On multi-tenant endpoints, optionally send x-username to act as an external user.'
  version: '1.0'
  contact:
    name: Flowra
    url: https://flowra.dev
servers:
- url: https://flowra.dev
  description: Flowra API
tags:
- name: Sandbox
  description: Ephemeral and durable code sandboxes
paths:
  /api/v1/sandbox/ephemeral:
    post:
      operationId: SandboxController_runEphemeral
      x-apiKeyEnabled: true
      summary: Run code in an ephemeral sandbox
      description: Create → run → kill. Use for tool script previews. Returns a structured status/result payload.
      parameters:
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxEphemeralDto'
      responses:
        '200':
          description: Ephemeral run result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxEphemeralResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  id: ''
                  status: succeeded
                  language: ''
                  result: {}
                  error: ''
                  durationMs: 0
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxEphemeralResponseDto'
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/sandbox/sessions:
    post:
      operationId: SandboxController_createSession
      x-apiKeyEnabled: true
      summary: Create a durable sandbox session
      description: Starts a persistent code sandbox billed for the session lifetime. Default threadId is http:{uuid}.
      parameters:
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxSessionDto'
      responses:
        '201':
          description: Sandbox session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSessionResponseDtoSuccessResponse'
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/sandbox/sessions/{id}:
    get:
      operationId: SandboxController_getSession
      x-apiKeyEnabled: true
      summary: Get sandbox session status
      description: Returns ownership-checked session status by ledger session id.
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Sandbox session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSessionResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  id: ''
                  sandboxId: ''
                  status: active
                  threadId: ''
                  cpuCount: 0
                  memoryMB: 0
                  maxDurationSec: 0
                  startedAt: ''
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    delete:
      operationId: SandboxController_releaseSession
      x-apiKeyEnabled: true
      summary: Release a sandbox session
      description: Kills the sandbox and settles billing for the session.
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Session released
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/sandbox/sessions/{id}/execute:
    post:
      operationId: SandboxController_executeInSession
      x-apiKeyEnabled: true
      summary: Execute code in a sandbox session
      description: Runs JavaScript or Python inside an existing live session. The session stays alive after the run.
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxSessionExecuteDto'
      responses:
        '200':
          description: Session execute result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxEphemeralResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  id: ''
                  status: succeeded
                  language: ''
                  result: {}
                  error: ''
                  durationMs: 0
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxEphemeralResponseDto'
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/sandbox/threads/{threadId}:
    get:
      operationId: SandboxController_getThreadComputer
      x-apiKeyEnabled: true
      summary: Chat computer status for a thread
      description: Returns power state (off/on/paused) for the agent-thread sandbox. Does not create a sandbox.
      parameters:
      - name: threadId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Chat computer status
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    delete:
      operationId: SandboxController_releaseThreadComputer
      x-apiKeyEnabled: true
      summary: Power off chat computer for a thread
      description: Releases the agent-thread sandbox and stops billing for it.
      parameters:
      - name: threadId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Chat computer status after release
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/sandbox/threads/{threadId}/start:
    post:
      operationId: SandboxController_startThreadComputer
      x-apiKeyEnabled: true
      summary: Warm-start chat computer for a thread
      description: 'Optional manual power-on: prepare/resume the agent-thread sandbox. Agents also auto-start on real FS/execute need.'
      parameters:
      - name: threadId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '201':
          description: Chat computer status after start
      tags:
      - Sandbox
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
components:
  schemas:
    SandboxSessionResponseDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            id:
              type: string
              description: Public session id (ledger UUID)
            sandboxId:
              type: string
              description: Provider sandbox id
            status:
              type: string
              enum:
              - active
              - settling
              - settled
              - failed
              description: Session status
            threadId:
              type:
              - string
              - 'null'
              description: Isolation thread id
            cpuCount:
              type: number
              description: vCPU count
            memoryMB:
              type: number
              description: Memory in MB
            maxDurationSec:
              type: number
              description: Max session duration in seconds
            startedAt:
              type: string
              description: Session start time (ISO)
          required:
          - id
          - sandboxId
          - status
          - cpuCount
          - memoryMB
          - maxDurationSec
          - startedAt
          example:
            id: ''
            sandboxId: ''
            status: active
            threadId: ''
            cpuCount: 0
            memoryMB: 0
            maxDurationSec: 0
            startedAt: ''
      required:
      - success
      - message
      - data
    SandboxEphemeralDto:
      type: object
      properties:
        language:
          enum:
          - javascript
          - python
          type: string
          description: Script language
          example: javascript
        source:
          type: string
          description: Script source (JavaScript or Python)
          example: 'export default async function ({ state }) { return { ...state, ok: true }; }'
        state:
          type: object
          description: State object passed to the script (default preview state if omitted)
          example:
            invoiceId: inv_123
        timeoutMs:
          type: number
          minimum: 1000
          maximum: 20000
          description: Timeout in milliseconds (default 8000, max 20000)
          default: 8000
          example: 8000
      required:
      - language
      - source
    CreateSandboxSessionDto:
      type: object
      properties:
        threadId:
          type: string
          description: Isolation thread id. Defaults to http:{uuid} so HTTP sessions do not collide with chat threads.
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
        workflowId:
          type: string
          description: Optional workflow id for billing attribution
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
        templateId:
          type: string
          description: Sandbox template name or id override
          example: code-interpreter-v1
        maxDurationSec:
          type: number
          minimum: 60
          maximum: 86400
          description: Max session duration in seconds (capped by server config)
          example: 3600
    SandboxSessionExecuteDto:
      type: object
      properties:
        language:
          enum:
          - javascript
          - python
          type: string
          description: Script language
          example: javascript
        source:
          type: string
          description: Script source (JavaScript or Python)
          example: 'export default async function ({ state }) { return { ...state, ok: true }; }'
        state:
          type: object
          description: State object passed to the script (default preview state if omitted)
          example:
            invoiceId: inv_123
        timeoutMs:
          type: number
          minimum: 1000
          maximum: 20000
          description: Timeout in milliseconds (default 8000, max 20000)
          default: 8000
          example: 8000
      required:
      - language
      - source
    SandboxEphemeralResponseDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            id:
              type: string
              description: Ephemeral run id
            status:
              type: string
              enum:
              - succeeded
              - failed
              description: Run outcome
            language:
              type: string
              description: Language used for the run
            result:
              type: object
              description: Result object when status is succeeded
            error:
              type: string
              description: Error message when status is failed
            durationMs:
              type: number
              description: Wall-clock duration in milliseconds
          required:
          - id
          - status
          - language
          example:
            id: ''
            status: succeeded
            language: ''
            result: {}
            error: ''
            durationMs: 0
      required:
      - success
      - message
      - data
    SandboxEphemeralResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Ephemeral run id
        status:
          type: string
          enum:
          - succeeded
          - failed
          description: Run outcome
        language:
          type: string
          description: Language used for the run
        result:
          type: object
          description: Result object when status is succeeded
        error:
          type: string
          description: Error message when status is failed
        durationMs:
          type: number
          description: Wall-clock duration in milliseconds
      required:
      - id
      - status
      - language
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Project API key. Create and manage keys in the dashboard under Project → API Keys. Send as header: x-api-key: <your-key>'
    x-username:
      type: apiKey
      in: header
      name: x-username
      description: 'Optional. External user username. If omitted, Flowra uses the project’s default external user. Send as header: x-username: <username>'