openapi: 3.0.3
info:
  title: Runloop agents Blueprint-ObservabilityTools API
  version: '0.1'
  description: Register, version, and mount Agents — packaged agent definitions sourced from Git, npm, pip, or storage objects that can be installed on Devboxes for fast, reproducible agent execution.
  contact:
    name: Runloop AI Support
    url: https://runloop.ai
    email: support@runloop.ai
servers:
- url: https://api.runloop.ai
  description: Runloop API
  variables: {}
security:
- bearerAuth: []
tags:
- name: Blueprint-ObservabilityTools
paths:
  /v1/blueprints/preview:
    post:
      tags:
      - Blueprint-ObservabilityTools
      summary: Preview Dockerfile definition for a Blueprint.
      description: Preview building a Blueprint with the specified configuration. You can take the resulting Dockerfile and test out your build using any local docker tooling.
      operationId: previewImage
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlueprintBuildParameters'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintPreviewView'
      deprecated: true
  /v1/blueprints/{id}/logs:
    get:
      tags:
      - Blueprint-ObservabilityTools
      summary: Get Blueprint build logs.
      description: Get all logs from the building of a Blueprint.
      operationId: blueprintLogs
      parameters:
      - name: id
        in: path
        description: The ID of the Blueprint
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintBuildLogsListView'
      deprecated: false
components:
  schemas:
    BlueprintBuildParameters:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the Blueprint.
        dockerfile:
          type: string
          nullable: true
          description: Dockerfile contents to be used to build the Blueprint.
        system_setup_commands:
          type: array
          items:
            type: string
          nullable: true
          description: A list of commands to run to set up your system.
        code_mounts:
          type: array
          items:
            $ref: '#/components/schemas/CodeMountParameters'
          nullable: true
          description: A list of code mounts to be included in the Blueprint.
        launch_parameters:
          $ref: '#/components/schemas/LaunchParameters'
          nullable: true
          description: Parameters to configure your Devbox at launch time.
        file_mounts:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: (Optional) Map of paths and file contents to write before setup.
        base_blueprint_id:
          type: string
          nullable: true
          description: (Optional) ID of previously built blueprint to use as a base blueprint for this build.
        base_blueprint_name:
          type: string
          nullable: true
          description: (Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.
        services:
          type: array
          items:
            $ref: '#/components/schemas/ContainerizedServiceView'
          nullable: true
          description: (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance.
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: (Optional) User defined metadata for the Blueprint.
        build_args:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: (Optional) Arbitrary Docker build args to pass during build.
        secrets:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: '(Optional) Map of mount IDs/environment variable names to secret names. Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {"DB_PASS": "DATABASE_PASSWORD"} makes the secret ''DATABASE_PASSWORD'' available as environment variable ''DB_PASS''.'
        build_context:
          $ref: '#/components/schemas/BuildContext'
          nullable: true
          description: (Optional) Build context to be attached to the Blueprint build. This context is the source of COPY and ADD directives.
        network_policy_id:
          type: string
          nullable: true
          description: (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.
      required:
      - name
    BlueprintBuildLogsListView:
      type: object
      additionalProperties: false
      properties:
        blueprint_id:
          type: string
          description: ID of the Blueprint.
        logs:
          type: array
          items:
            $ref: '#/components/schemas/BlueprintBuildLog'
          description: List of logs generated during Blueprint build.
      required:
      - blueprint_id
      - logs
    LifecycleConfigurationParameters:
      type: object
      additionalProperties: false
      description: Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle and resume triggers via resume_triggers.
      properties:
        after_idle:
          $ref: '#/components/schemas/IdleConfigurationParameters'
          nullable: true
          description: Configure Devbox lifecycle based on idle activity. If both this and the top-level after_idle are set, they must have the same value. Prefer this field for new integrations.
        resume_triggers:
          $ref: '#/components/schemas/ResumeTriggers'
          nullable: true
          description: Triggers that can resume a suspended Devbox.
    Architecture:
      type: string
      enum:
      - x86_64
      - arm64
    CodeMountParameters:
      type: object
      additionalProperties: false
      properties:
        repo_name:
          type: string
          description: The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}.
        repo_owner:
          type: string
          description: The owner of the repo.
        install_command:
          type: string
          nullable: true
          description: Installation command to install and setup repository.
        git_ref:
          type: string
          nullable: true
          description: Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.
        token:
          type: string
          nullable: true
          description: The authentication token necessary to pull repo.
      required:
      - repo_name
      - repo_owner
    Credentials:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          description: The username of the container service.
        password:
          type: string
          description: The password of the container service.
      required:
      - username
      - password
    ResumeTriggers:
      type: object
      additionalProperties: false
      description: Triggers that can resume a suspended Devbox.
      properties:
        http:
          type: boolean
          nullable: true
          description: When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.
        axon_event:
          type: boolean
          nullable: true
          description: When true, axon events targeting a suspended Devbox will trigger a resume.
    ResourceSize:
      type: string
      enum:
      - X_SMALL
      - SMALL
      - MEDIUM
      - LARGE
      - X_LARGE
      - XX_LARGE
      - CUSTOM_SIZE
      description: 'The size of the Devbox resources for Runloop to allocate.


        X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk

        SMALL: 1 cpu x 2GiB memory x 4GiB disk

        MEDIUM: 2 cpu x 4GiB memory x 8GiB disk

        LARGE: 2 cpu x 8GiB memory x 16GiB disk

        X_LARGE: 4 cpu x 16GiB memory x 16GiB disk

        XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk

        CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.

        '
      x-enum-descriptions:
        X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk
        SMALL: 1 cpu x 2GiB memory x 4GiB disk
        MEDIUM: 2 cpu x 4GiB memory x 8GiB disk
        LARGE: 2 cpu x 8GiB memory x 16GiB disk
        X_LARGE: 4 cpu x 16GiB memory x 16GiB disk
        XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk
        CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.
    UserParameters:
      type: object
      additionalProperties: false
      description: Configuration for the Linux user in the Devbox environment.
      properties:
        username:
          type: string
          description: Username for the Linux user.
        uid:
          type: integer
          format: int32
          description: User ID (UID) for the Linux user. Must be a non-negative integer.
      required:
      - username
      - uid
    IdleConfigurationParameters:
      type: object
      additionalProperties: false
      properties:
        idle_time_seconds:
          type: integer
          format: int32
          description: After idle_time_seconds, on_idle action will be taken.
        on_idle:
          $ref: '#/components/schemas/IdleAction'
          description: Action to take after Devbox becomes idle.
      required:
      - idle_time_seconds
      - on_idle
    LaunchParameters:
      type: object
      additionalProperties: false
      description: LaunchParameters enable you to customize the resources available to your Devbox as well as the environment set up that should be completed before the Devbox is marked as 'running'.
      properties:
        launch_commands:
          type: array
          items:
            type: string
          nullable: true
          description: Set of commands to be run at launch time, before the entrypoint process is run.
        resource_size_request:
          $ref: '#/components/schemas/ResourceSize'
          nullable: true
          description: 'Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set, SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32 GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size.'
        available_ports:
          type: array
          items:
            type: integer
            format: int32
          nullable: true
          description: '[Deprecated] A list of ports to make available on the Devbox. This field is ignored.'
        keep_alive_time_seconds:
          type: integer
          format: int64
          nullable: true
          description: Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).
        after_idle:
          $ref: '#/components/schemas/IdleConfigurationParameters'
          nullable: true
          description: Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead.
        custom_cpu_cores:
          type: integer
          format: int32
          nullable: true
          description: Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.
        custom_gb_memory:
          type: integer
          format: int32
          nullable: true
          description: Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.
        custom_disk_size:
          type: integer
          format: int32
          nullable: true
          description: Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.
        architecture:
          $ref: '#/components/schemas/Architecture'
          nullable: true
          description: The target architecture for the Devbox. If unset, defaults to x86_64.
        user_parameters:
          $ref: '#/components/schemas/UserParameters'
          nullable: true
          description: Specify the user for execution on Devbox. If not set, default `user` will be used.
        required_services:
          type: array
          items:
            type: string
          nullable: true
          description: A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started.
        network_policy_id:
          type: string
          nullable: true
          description: (Optional) ID of the network policy to apply to Devboxes launched with these parameters. When set on a Blueprint launch parameters, Devboxes created from it will inherit this policy unless explicitly overridden.
        lifecycle:
          $ref: '#/components/schemas/LifecycleConfigurationParameters'
          nullable: true
          description: Lifecycle configuration for idle and resume behavior. Configure idle policy via lifecycle.after_idle (if both this and the top-level after_idle are set, they must match) and resume triggers via lifecycle.resume_triggers.
    BlueprintBuildLog:
      type: object
      additionalProperties: false
      properties:
        level:
          type: string
          description: Log line severity level.
        timestamp_ms:
          type: integer
          format: int64
          description: Time of log (Unix timestamp milliseconds).
        message:
          type: string
          description: Log line message.
      required:
      - level
      - timestamp_ms
      - message
    IdleAction:
      type: string
      enum:
      - shutdown
      - suspend
      description: 'Action to take after Devbox idle timer is triggered.


        shutdown: Shutdown the Devbox.

        suspend: Suspend the Devbox.

        '
      x-enum-descriptions:
        shutdown: Shutdown the Devbox.
        suspend: Suspend the Devbox.
    ObjectContext:
      type: object
      additionalProperties: false
      description: A build context backed by an Object.
      properties:
        object_id:
          type: string
          description: The ID of an object, whose contents are to be used as a build context.
        type:
          type: string
          enum:
          - object
          default: object
      required:
      - object_id
      - type
    BuildContext:
      oneOf:
      - $ref: '#/components/schemas/ObjectContext'
      discriminator:
        propertyName: type
        mapping:
          object: '#/components/schemas/ObjectContext'
    ContainerizedServiceView:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the container service.
        image:
          type: string
          description: The image of the container service.
        credentials:
          $ref: '#/components/schemas/Credentials'
          nullable: true
          description: The credentials of the container service.
        env:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: The environment variables of the container service.
        port_mappings:
          type: array
          items:
            type: string
          nullable: true
          description: The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.
        options:
          type: string
          nullable: true
          description: Additional Docker container create options.
      required:
      - name
      - image
    BlueprintPreviewView:
      type: object
      additionalProperties: false
      properties:
        dockerfile:
          type: string
          description: The Dockerfile contents that will built.
      required:
      - dockerfile
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http