openapi: 3.0.3
info:
title: Runloop Blueprint API
version: '0.1'
description: "Build and manage Blueprints \u2014 Dockerfile-based container image templates for fast Devbox startup with\
\ pre-installed dependencies, system packages, and tooling. Supports building, previewing, listing public blueprints,\
\ and metadata-based discovery."
contact:
name: Runloop AI Support
url: https://runloop.ai
email: [email protected]
servers:
- url: https://api.runloop.ai
description: Runloop API
variables: {}
tags:
- name: Blueprint
- name: Blueprint-Lifecycle
- name: Blueprint-ObservabilityTools
paths:
/v1/blueprints:
post:
tags:
- Blueprint
- Blueprint-Lifecycle
summary: Create and build a Blueprint.
description: Starts build of custom defined container Blueprint. The Blueprint will begin in the 'provisioning' step
and transition to the 'building' step once it is selected off the build queue., Upon build complete it will transition
to 'building_complete' if the build is successful.
operationId: createBlueprint
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintBuildParameters'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintView'
deprecated: false
get:
tags:
- Blueprint
summary: List Blueprints.
description: List all Blueprints or filter by name.
operationId: listImages
parameters:
- name: name
in: query
description: Filter by name
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: status
in: query
description: Filter by build status (queued, provisioning, building, failed, build_complete)
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: limit
in: query
description: The limit of items to return. Default is 20. Max is 5000.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: integer
format: int32
- name: starting_after
in: query
description: Load the next page of data starting after the item with the given ID.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: include_total_count
in: query
description: If true (default), includes total_count in the response. Set to false to skip the count query for better
performance on large datasets.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintListView'
deprecated: false
/v1/blueprints/create_from_inspection:
post:
tags:
- Blueprint
- Blueprint-Lifecycle
summary: Create and build a Blueprint from a RepositoryConnection Inspection.
description: Starts build of custom defined container Blueprint using a RepositoryConnection Inspection as a source
container specification.
operationId: createBlueprintFromInspection
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintBuildFromInspectionParameters'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintView'
deprecated: false
/v1/blueprints/list_public:
get:
tags:
- Blueprint
summary: List Public Blueprints.
description: List all public Blueprints that are available to all users.
operationId: listPublicBlueprints
parameters:
- name: name
in: query
description: Filter by name
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: status
in: query
description: Filter by build status (queued, provisioning, building, failed, build_complete)
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: limit
in: query
description: The limit of items to return. Default is 20. Max is 5000.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: integer
format: int32
- name: starting_after
in: query
description: Load the next page of data starting after the item with the given ID.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: string
- name: include_total_count
in: query
description: If true (default), includes total_count in the response. Set to false to skip the count query for better
performance on large datasets.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BlueprintListView'
deprecated: false
/v1/blueprints/metadata/keys:
get:
tags:
- Blueprint
summary: List available blueprint metadata keys.
description: Returns a list of all available metadata keys that can be used for filtering blueprints.
operationId: getBlueprintMetadataKeys
parameters: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataKeysView'
deprecated: false
/v1/blueprints/metadata/keys/{key}/values:
get:
tags:
- Blueprint
summary: List values for a specific blueprint metadata key.
description: Returns a list of all values that exist for a specific metadata key across all blueprints.
operationId: getBlueprintMetadataValues
parameters:
- name: key
in: path
description: The metadata key to get values for.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataValuesView'
'400':
description: Invalid metadata key provided.
deprecated: false
/v1/blueprints/preview:
post:
tags:
- Blueprint
- 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/public/metadata/keys:
get:
tags:
- Blueprint
summary: List available public blueprint metadata keys.
description: Returns a list of all available metadata keys from public blueprints only that can be used for filtering.
operationId: getPublicBlueprintMetadataKeys
parameters: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataKeysView'
deprecated: false
/v1/blueprints/public/metadata/keys/{key}/values:
get:
tags:
- Blueprint
summary: List values for a specific public blueprint metadata key.
description: Returns a list of all values that exist for a specific metadata key across all public blueprints only.
operationId: getPublicBlueprintMetadataValues
parameters:
- name: key
in: path
description: The metadata key to get values for from public blueprints.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataValuesView'
'400':
description: Invalid metadata key provided.
deprecated: false
/v1/blueprints/{id}:
get:
tags:
- Blueprint
- Blueprint-Lifecycle
summary: Get a Blueprint.
description: Get the details of a previously created Blueprint including the build status.
operationId: getBlueprint
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/BlueprintView'
deprecated: false
/v1/blueprints/{id}/delete:
post:
tags:
- Blueprint
summary: Delete a Blueprint.
description: 'Delete a previously created Blueprint. If a blueprint has dependent snapshots, it cannot be deleted. You
can find them by querying: GET /v1/devboxes/disk_snapshots?source_blueprint_id={blueprint_id}.'
operationId: deleteBlueprint
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/EmptyRecord'
'400':
description: Blueprint has dependent snapshots that must be deleted first. Returns list of snapshot IDs.
'404':
description: Blueprint not found.
deprecated: false
/v1/blueprints/{id}/logs:
get:
tags:
- Blueprint
- 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:
Architecture:
type: string
enum:
- x86_64
- arm64
BlueprintBuildFailureReason:
type: string
enum:
- out_of_memory
- out_of_disk
- build_failed
description: 'The cause of the failure of the Blueprint build.
out_of_memory: The build has run out of memory. Contact support if this is unexpected.
out_of_disk: The build has run out of disk. Contact support if this is unexpected.
build_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info.
'
x-enum-descriptions:
out_of_memory: The build has run out of memory. Contact support if this is unexpected.
out_of_disk: The build has run out of disk. Contact support if this is unexpected.
build_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info.
BlueprintBuildFromInspectionParameters:
type: object
additionalProperties: false
properties:
name:
type: string
description: Name of the Blueprint.
inspection_source:
$ref: '#/components/schemas/InspectionSource'
description: (Optional) Use a RepositoryInspection a source of a Blueprint build. The Dockerfile will be automatically
created based on the RepositoryInspection contents.
system_setup_commands:
type: array
items:
type: string
nullable: true
description: A list of commands to run to set up your system.
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.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: (Optional) User defined metadata for the Blueprint.
secrets:
type: object
additionalProperties:
type: string
nullable: true
description: '(Optional) Map of mount IDs/environment variable names to secret names. Secrets can be used as environment
variables in system_setup_commands. Example: {"GITHUB_TOKEN": "gh_secret"} makes ''gh_secret'' available as GITHUB_TOKEN.'
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.
required:
- name
- inspection_source
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
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
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
BlueprintBuildStatus:
type: string
enum:
- queued
- provisioning
- building
- failed
- build_complete
description: 'The status of the Blueprint build.
queued: Blueprint is queued waiting for build capacity to become available.
provisioning: Allocating and booting the necessary infrastructure resources to create the Blueprint image.
building: Building the Blueprint image.
failed: Blueprint image failed to build. See the logs on the dashboard.
build_complete: Blueprint image completed build. You can now use the ID to create Devboxes.
'
x-enum-descriptions:
queued: Blueprint is queued waiting for build capacity to become available.
provisioning: Allocating and booting the necessary infrastructure resources to create the Blueprint image.
building: Building the Blueprint image.
failed: Blueprint image failed to build. See the logs on the dashboard.
build_complete: Blueprint image completed build. You can now use the ID to create Devboxes.
BlueprintListView:
type: object
additionalProperties: false
properties:
blueprints:
type: array
items:
$ref: '#/components/schemas/BlueprintView'
description: List of blueprints matching filter.
has_more:
type: boolean
total_count:
type: integer
format: int32
nullable: true
required:
- blueprints
- has_more
BlueprintPreviewView:
type: object
additionalProperties: false
properties:
dockerfile:
type: string
description: The Dockerfile contents that will built.
required:
- dockerfile
BlueprintState:
type: string
enum:
- created
- deleted
BlueprintView:
type: object
additionalProperties: false
description: Blueprints are ways to create customized starting points for Devboxes. They allow you to define custom
starting points for Devboxes such that environment set up can be cached to improve Devbox boot times.
properties:
id:
type: string
description: The id of the Blueprint.
name:
type: string
description: The name of the Blueprint.
status:
$ref: '#/components/schemas/BlueprintBuildStatus'
description: The status of the Blueprint build.
state:
$ref: '#/components/schemas/BlueprintState'
description: The state of the Blueprint.
create_time_ms:
type: integer
format: int64
description: Creation time of the Blueprint (Unix timestamp milliseconds).
build_finish_time_ms:
type: integer
format: int64
nullable: true
description: Build completion time of the Blueprint (Unix timestamp milliseconds).
parameters:
$ref: '#/components/schemas/BlueprintBuildParameters'
description: The parameters used to create Blueprint.
failure_reason:
$ref: '#/components/schemas/BlueprintBuildFailureReason'
nullable: true
description: The failure reason if the Blueprint build failed, if any.
base_blueprint_id:
type: string
nullable: true
description: The ID of the base Blueprint.
containerized_services:
type: array
items:
$ref: '#/components/schemas/ContainerizedServiceView'
nullable: true
description: List of ContainerizedServices available in the Blueprint. Services can be explicitly started when creating
a Devbox.
is_public:
type: boolean
description: Whether this Blueprint is publicly accessible to all users.
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: User defined metadata associated with the blueprint.
devbox_capabilities:
type: array
items:
$ref: '#/components/schemas/DevboxCapabilities'
nullable: true
description: Capabilities that will be available on Devbox.
required:
- id
- name
- status
- state
- create_time_ms
- parameters
BuildContext:
oneOf:
- $ref: '#/components/schemas/ObjectContext'
discriminator:
propertyName: type
mapping:
object: '#/components/schemas/ObjectContext'
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
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
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
DevboxCapabilities:
type: string
enum:
- unknown
- docker_in_docker
EmptyRecord:
type: object
additionalProperties: false
properties: {}
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.
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
InspectionSource:
type: object
additionalProperties: false
description: Use a RepositoryInspection a source of a Blueprint build.
properties:
inspection_id:
type: string
description: The ID of a repository inspection.
github_auth_token:
type: string
nullable: true
description: GitHub authentication token for accessing private repositories.
required:
- inspection_id
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.
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.
MetadataKeysView:
type: object
additionalProperties: false
properties:
keys:
type: array
items:
type: string
MetadataValuesView:
type: object
additionalProperties: false
properties:
key:
type: string
values:
type: array
items:
type: string
ObjectContext:
type: object
additionalProperties: false
description: A build context backed by an Object.
properties:
object_id:
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runloop-ai/refs/heads/main/openapi/runloop-blueprint-api-openapi.yml