{ "openapi": "3.1.0", "info": { "title": "RunLoop API", "version": "0.1", "description": "The RunLoop API spec that allows you to host lambda functions and Devboxes to enable scaled long running ai workflows.", "contact": { "name": "Runloop AI Support", "url": "https://runloop.ai", "email": "support@runloop.ai" } }, "servers": [ { "url": "https://api.runloop.ai", "description": "Runloop API", "variables": {} } ], "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } }, "schemas": { "AccountBillingType": { "type": "string", "enum": ["STRIPE", "AWS_MARKETPLACE", "STRIPE_PROJECTS", "UNRECOGNIZED"] }, "AccountStatus": { "type": "string", "enum": [ "ACCOUNT_STATUS_INVALID", "ACCOUNT_STATUS_ONBOARDING", "ACCOUNT_STATUS_ENABLED", "ACCOUNT_STATUS_DISABLED_BY_ADMIN", "ACCOUNT_STATUS_DISABLED_QUOTA_REACHED", "ACCOUNT_STATUS_TRIAL_CANCELLED", "ACCOUNT_STATUS_STRIPE_PENDING_RESOURCES", "UNRECOGNIZED" ] }, "AccountTier": { "type": "string", "enum": [ "ACCOUNT_TIER_INVALID", "ACCOUNT_TIER_BASIC", "ACCOUNT_TIER_PRO", "ACCOUNT_TIER_ENTERPRISE", "ACCOUNT_TIER_TRIAL", "UNRECOGNIZED" ] }, "AccountView": { "type": "object", "description": "Account information.", "properties": { "id": { "type": "string", "description": "The account ID." }, "name": { "type": "string", "description": "The account name." }, "tier": { "$ref": "#/components/schemas/AccountTier", "description": "The account tier." }, "account_status": { "$ref": "#/components/schemas/AccountStatus", "description": "The account status." }, "created_at": { "type": "string", "description": "The account creation timestamp." }, "billing": { "$ref": "#/components/schemas/BillingView", "description": "The account billing information." }, "stripe_customer_id": { "description": "Deprecated: use billing.stripe.customer_id.", "type": ["string", "null"] }, "active_subscription": { "description": "Deprecated: use billing.stripe.active_subscription.", "type": ["string", "null"] }, "account_billing_type": { "$ref": "#/components/schemas/AccountBillingType", "description": "Deprecated: use billing.account_billing_type." }, "external_billing_account_id": { "description": "Deprecated: use billing.aws.customer_identifier.", "type": ["string", "null"] } }, "required": [ "id", "name", "tier", "account_status", "created_at", "billing" ] }, "AgentCreateParameters": { "type": "object", "description": "Parameters for creating a new Agent.", "properties": { "name": { "type": "string", "description": "The name of the Agent." }, "version": { "description": "Optional version identifier for the Agent. For npm/pip sources this is typically a semver string (e.g. '2.0.65'). For git sources it can be a branch or tag. Semantics are user-defined for object sources.", "type": ["string", "null"] }, "source": { "description": "The source configuration for the Agent.", "anyOf": [ { "$ref": "#/components/schemas/AgentSource" }, { "type": "null" } ] } }, "required": ["name"] }, "AgentDevboxCountsView": { "type": "object", "description": "Devbox counts grouped by agent name. Used to efficiently fetch devbox counts for multiple agents in a single request.", "properties": { "counts": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Map of agent name to devbox count. Each key is an agent name, and the value is the count of devboxes associated with that agent." }, "total_count": { "type": "integer", "format": "int32", "description": "Total count of devboxes across all agents in the result." } }, "required": ["counts", "total_count"] }, "AgentListView": { "type": "object", "description": "A paginated list of Agents.", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentView" }, "description": "The list of Agents." }, "has_more": { "type": "boolean", "description": "Whether there are more Agents to fetch." }, "total_count": { "format": "int32", "description": "The total count of Agents.", "type": ["integer", "null"] } }, "required": ["agents", "has_more"] }, "AgentMount": { "type": "object", "properties": { "agent_id": { "description": "The ID of the agent to mount. Either agent_id or name must be set.", "type": ["string", "null"] }, "agent_name": { "description": "The name of the agent to mount. Returns the most recent agent with a matching name if no agent id string provided. Either agent id or name must be set", "type": ["string", "null"] }, "agent_path": { "description": "Path to mount the agent on the Devbox. Required for git and object agents. Use absolute path (e.g., /home/user/agent)", "type": ["string", "null"] }, "auth_token": { "description": "Optional auth token for private repositories. Only used for git agents.", "type": ["string", "null"] }, "type": { "type": "string", "enum": ["agent_mount"], "default": "agent_mount" } }, "required": ["agent_id", "agent_name", "type"] }, "AgentSource": { "type": "object", "description": "Agent source configuration.", "properties": { "type": { "type": "string", "description": "Source type: npm, pip, object, or git" }, "npm": { "description": "NPM source configuration", "anyOf": [ { "$ref": "#/components/schemas/NpmSource" }, { "type": "null" } ] }, "pip": { "description": "Pip source configuration", "anyOf": [ { "$ref": "#/components/schemas/PipSource" }, { "type": "null" } ] }, "object": { "description": "Object store source configuration", "anyOf": [ { "$ref": "#/components/schemas/ObjectSource" }, { "type": "null" } ] }, "git": { "description": "Git source configuration", "anyOf": [ { "$ref": "#/components/schemas/GitSource" }, { "type": "null" } ] } }, "required": ["type"] }, "AgentView": { "type": "object", "description": "An Agent represents a registered AI agent entity.", "properties": { "id": { "type": "string", "description": "The unique identifier of the Agent." }, "name": { "type": "string", "description": "The name of the Agent." }, "version": { "description": "Optional version identifier for the Agent. For npm/pip sources this is typically a semver string (e.g. '2.0.65'). For git sources it can be a branch or tag. Omitted for object sources or when not provided.", "type": ["string", "null"] }, "create_time_ms": { "type": "integer", "format": "int64", "description": "The creation time of the Agent (Unix timestamp milliseconds)." }, "is_public": { "type": "boolean", "description": "Whether the Agent is publicly accessible." }, "source": { "description": "The source configuration for the Agent.", "anyOf": [ { "$ref": "#/components/schemas/AgentSource" }, { "type": "null" } ] } }, "required": ["id", "name", "create_time_ms", "is_public"] }, "AllowedCidr": { "type": "object", "description": "A CIDR-based egress allow rule with optional port restrictions.", "properties": { "cidr": { "type": "string", "description": "IPv4 CIDR block in canonical form (host bits zero), e.g. '10.12.0.0/16'." }, "ports": { "items": { "$ref": "#/components/schemas/PortRule" }, "description": "(Optional) Ports allowed for this CIDR. Empty or omitted means all ports and protocols.", "type": ["array", "null"] } }, "required": ["cidr"] }, "ApiAccessLevel": { "type": "string", "enum": ["ACCESS_LEVEL_NONE", "ACCESS_LEVEL_READ", "ACCESS_LEVEL_WRITE"] }, "ApiKeyCreateParameters": { "type": "object", "properties": { "name": { "type": "string" }, "expires_at_ms": { "format": "int64", "type": ["integer", "null"] } } }, "ApiKeyCreatedView": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_secret": { "type": "string" }, "expires_at_ms": { "format": "int64", "type": ["integer", "null"] } } }, "ApiResourceType": { "type": "string", "enum": [ "RESOURCE_TYPE_DEVBOXES", "RESOURCE_TYPE_BLUEPRINTS", "RESOURCE_TYPE_SNAPSHOTS", "RESOURCE_TYPE_AGENTS", "RESOURCE_TYPE_OBJECTS", "RESOURCE_TYPE_ACCOUNT" ] }, "Architecture": { "type": "string", "enum": ["x86_64", "arm64"] }, "AuthMechanismView": { "type": "object", "description": "Defines how the primary credential is applied to requests proxied to the upstream.", "properties": { "type": { "type": "string", "description": "The type of authentication mechanism: 'header', 'bearer', or 'basic'. For 'basic', store the secret as plain 'user:pass'; the proxy base64-encodes it." }, "key": { "description": "The header name (e.g., 'x-api-key'). Required for 'header' type; invalid for other types.", "type": ["string", "null"] } }, "required": ["type"] }, "AwsBillingInfo": { "type": "object", "description": "AWS Marketplace billing information.", "properties": { "customer_identifier": { "description": "The AWS account ID used for Marketplace billing (12-digit).", "type": ["string", "null"] }, "license_arn": { "description": "The AWS Marketplace license ARN.", "type": ["string", "null"] }, "subscription_status": { "description": "The AWS Marketplace subscription status.", "type": ["string", "null"] } } }, "AxonCreateParams": { "type": "object", "properties": { "name": { "description": "(Optional) Name for the axon.", "type": ["string", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to attach to the axon for organization.", "type": ["object", "null"] } } }, "AxonEventListView": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AxonEventView" }, "description": "List of axon events." }, "has_more": { "type": "boolean" }, "total_count": { "format": "int32", "type": ["integer", "null"] } }, "required": ["events", "has_more"] }, "AxonEventOrigin": { "type": "string", "enum": ["EXTERNAL_EVENT", "AGENT_EVENT", "USER_EVENT", "SYSTEM_EVENT"], "description": "Event origin classification." }, "AxonEventView": { "type": "object", "properties": { "sequence": { "type": "integer", "format": "int64", "description": "Monotonic sequence number." }, "axon_id": { "type": "string", "description": "The axon identifier." }, "timestamp_ms": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds since epoch." }, "origin": { "$ref": "#/components/schemas/AxonEventOrigin", "description": "Event origin." }, "source": { "type": "string", "description": "Event source (e.g. github, slack)." }, "event_type": { "type": "string", "description": "Event type (e.g. push, pull_request)." }, "payload": { "type": "string", "description": "JSON-encoded event payload." } }, "required": [ "sequence", "axon_id", "timestamp_ms", "origin", "source", "event_type", "payload" ] }, "AxonListView": { "type": "object", "properties": { "axons": { "type": "array", "items": { "$ref": "#/components/schemas/AxonView" }, "description": "List of active axons." }, "has_more": { "type": "boolean" }, "total_count": { "format": "int32", "type": ["integer", "null"] } }, "required": ["axons", "has_more"] }, "AxonUpdateParams": { "type": "object", "properties": { "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to replace the axon metadata. Omit or set to null to leave unchanged, or set to an empty map to clear it.", "type": ["object", "null"] } } }, "AxonView": { "type": "object", "properties": { "id": { "type": "string", "description": "The axon identifier." }, "name": { "description": "The name of the axon.", "type": ["string", "null"] }, "created_at_ms": { "type": "integer", "format": "int64", "description": "Creation time in milliseconds since epoch." }, "deleted_at_ms": { "format": "int64", "description": "Deletion time in milliseconds since epoch; null while the axon is active.", "type": ["integer", "null"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The user defined axon metadata." } }, "required": ["id", "created_at_ms", "metadata"] }, "BillingView": { "type": "object", "description": "Account billing information.", "properties": { "account_billing_type": { "$ref": "#/components/schemas/AccountBillingType", "description": "The account billing type." }, "stripe": { "description": "Stripe billing information, when the account is billed via Stripe.", "anyOf": [ { "$ref": "#/components/schemas/StripeBillingInfo" }, { "type": "null" } ] }, "aws": { "description": "AWS Marketplace billing information, when the account is billed via AWS.", "anyOf": [ { "$ref": "#/components/schemas/AwsBillingInfo" }, { "type": "null" } ] }, "stripe_customer_id": { "description": "Deprecated: use stripe.customer_id.", "type": ["string", "null"] } }, "required": ["account_billing_type"] }, "BlueprintBuildFailureReason": { "type": "string", "enum": ["out_of_memory", "out_of_disk", "build_failed"], "description": "The cause of the failure of the Blueprint build.\n\nout_of_memory: The build has run out of memory. Contact support if this is unexpected.\nout_of_disk: The build has run out of disk. Contact support if this is unexpected.\nbuild_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info.\n", "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." } }, "BlueprintBuildLog": { "type": "object", "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", "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", "properties": { "name": { "type": "string", "description": "Name of the Blueprint." }, "dockerfile": { "description": "Dockerfile contents to be used to build the Blueprint.", "type": ["string", "null"] }, "system_setup_commands": { "items": { "type": "string" }, "description": "A list of commands to run to set up your system.", "type": ["array", "null"] }, "code_mounts": { "items": { "$ref": "#/components/schemas/CodeMountParameters" }, "description": "A list of code mounts to be included in the Blueprint.", "type": ["array", "null"] }, "launch_parameters": { "description": "Parameters to configure your Devbox at launch time.", "anyOf": [ { "$ref": "#/components/schemas/LaunchParameters" }, { "type": "null" } ] }, "file_mounts": { "additionalProperties": { "type": "string" }, "description": "(Optional) Map of paths and file contents to write before setup.", "type": ["object", "null"] }, "base_blueprint_id": { "description": "(Optional) ID of previously built blueprint to use as a base blueprint for this build.", "type": ["string", "null"] }, "base_blueprint_name": { "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.", "type": ["string", "null"] }, "services": { "items": { "$ref": "#/components/schemas/ContainerizedServiceView" }, "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.", "type": ["array", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "(Optional) User defined metadata for the Blueprint.", "type": ["object", "null"] }, "build_args": { "additionalProperties": { "type": "string" }, "description": "(Optional) Arbitrary Docker build args to pass during build.", "type": ["object", "null"] }, "secrets": { "additionalProperties": { "type": "string" }, "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'.", "type": ["object", "null"] }, "build_context": { "description": "(Optional) Build context to be attached to the Blueprint build. This context is the source of COPY and ADD directives.", "anyOf": [ { "$ref": "#/components/schemas/BuildContext" }, { "type": "null" } ] }, "network_policy_id": { "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.", "type": ["string", "null"] } }, "required": ["name"] }, "BlueprintBuildStatus": { "type": "string", "enum": [ "queued", "provisioning", "building", "awaiting_upload", "failed", "build_complete" ], "description": "The status of the Blueprint build.\n\nqueued: Blueprint is queued waiting for build capacity to become available.\nprovisioning: Allocating and booting the necessary infrastructure resources to create the Blueprint image.\nbuilding: Building the Blueprint image.\nawaiting_upload: Blueprint is created and awaiting its image to be pushed out-of-band via docker push.\nfailed: Blueprint image failed to build. See the logs on the dashboard.\nbuild_complete: Blueprint image completed build. You can now use the ID to create Devboxes.\n", "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.", "awaiting_upload": "Blueprint is created and awaiting its image to be pushed out-of-band via docker push.", "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", "properties": { "blueprints": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintView" }, "description": "List of blueprints matching filter." }, "has_more": { "type": "boolean" }, "total_count": { "format": "int32", "type": ["integer", "null"] } }, "required": ["blueprints", "has_more"] }, "BlueprintPreviewView": { "type": "object", "properties": { "dockerfile": { "type": "string", "description": "The Dockerfile contents that will built." } }, "required": ["dockerfile"] }, "BlueprintState": { "type": "string", "enum": ["created", "deleted"] }, "BlueprintView": { "type": "object", "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": { "format": "int64", "description": "Build completion time of the Blueprint (Unix timestamp milliseconds).", "type": ["integer", "null"] }, "parameters": { "$ref": "#/components/schemas/BlueprintBuildParameters", "description": "The parameters used to create Blueprint." }, "failure_reason": { "description": "The failure reason if the Blueprint build failed, if any.", "anyOf": [ { "$ref": "#/components/schemas/BlueprintBuildFailureReason" }, { "type": "null" } ] }, "base_blueprint_id": { "description": "The ID of the base Blueprint.", "type": ["string", "null"] }, "containerized_services": { "items": { "$ref": "#/components/schemas/ContainerizedServiceView" }, "description": "List of ContainerizedServices available in the Blueprint. Services can be explicitly started when creating a Devbox.", "type": ["array", "null"] }, "is_public": { "type": "boolean", "description": "Whether this Blueprint is publicly accessible to all users." }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata associated with the blueprint.", "type": ["object", "null"] }, "devbox_capabilities": { "items": { "$ref": "#/components/schemas/DevboxCapabilities" }, "description": "Capabilities that will be available on Devbox.", "type": ["array", "null"] } }, "required": [ "id", "name", "status", "state", "create_time_ms", "parameters" ] }, "BrokerMount": { "type": "object", "properties": { "axon_id": { "type": "string", "description": "The ID of the axon event stream to mount onto the Devbox." }, "protocol": { "description": "The protocol used by the broker to deliver events to the agent.", "anyOf": [ { "$ref": "#/components/schemas/BrokerMountProtocol" }, { "type": "null" } ] }, "agent_binary": { "description": "Binary to launch the agent (e.g., 'opencode'). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).", "type": ["string", "null"] }, "working_directory": { "description": "Working directory in which to launch the agent binary. Defaults to the home directory if not specified.", "type": ["string", "null"] }, "launch_args": { "items": { "type": "string" }, "description": "Arguments to pass to the agent command (e.g., ['acp']). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).", "type": ["array", "null"] }, "type": { "type": "string", "enum": ["broker_mount"], "default": "broker_mount" } }, "required": ["axon_id", "type"] }, "BrokerMountProtocol": { "type": "string", "enum": ["acp", "claude_json", "codex_json", "pi_json"] }, "BuildContext": { "oneOf": [ { "$ref": "#/components/schemas/ObjectContext" } ], "discriminator": { "propertyName": "type", "mapping": { "object": "#/components/schemas/ObjectContext" } } }, "CodeMount": { "type": "object", "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": { "description": "Installation command to install and setup repository.", "type": ["string", "null"] }, "git_ref": { "description": "Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.", "type": ["string", "null"] }, "token": { "description": "The authentication token necessary to pull repo.", "type": ["string", "null"] }, "type": { "type": "string", "enum": ["code_mount"], "default": "code_mount" } }, "required": ["repo_name", "repo_owner", "type"] }, "CodeMountParameters": { "type": "object", "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": { "description": "Installation command to install and setup repository.", "type": ["string", "null"] }, "git_ref": { "description": "Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.", "type": ["string", "null"] }, "token": { "description": "The authentication token necessary to pull repo.", "type": ["string", "null"] } }, "required": ["repo_name", "repo_owner"] }, "ContainerizedServiceView": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the container service." }, "image": { "type": "string", "description": "The image of the container service." }, "credentials": { "description": "The credentials of the container service.", "anyOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "null" } ] }, "env": { "additionalProperties": { "type": "string" }, "description": "The environment variables of the container service.", "type": ["object", "null"] }, "port_mappings": { "items": { "type": "string" }, "description": "The port mappings of the container service. Port mappings are in the format of :.", "type": ["array", "null"] }, "options": { "description": "Additional Docker container create options.", "type": ["string", "null"] } }, "required": ["name", "image"] }, "ContentType": { "type": "string", "enum": ["unspecified", "text", "binary", "gzip", "tar", "tgz"] }, "Credentials": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the container service." }, "password": { "type": "string", "description": "The password of the container service." } }, "required": ["username", "password"] }, "CustomHeaderView": { "type": "object", "description": "An additional header applied to upstream requests alongside the primary credential. The value comes from an account secret or a literal string; exactly one of 'secret' and 'value' must be set.", "properties": { "name": { "type": "string", "description": "The header name (e.g., 'DD-APPLICATION-KEY')." }, "secret": { "description": "Account secret providing the header value. Accepts a secret name or 'sec_' id on writes; reads always return the 'sec_' id.", "type": ["string", "null"] }, "value": { "description": "Literal header value. Stored in plaintext and returned by reads - use 'secret' for credentials or other sensitive values.", "type": ["string", "null"] } }, "required": ["name"] }, "DevboxAsyncExecutionDetailView": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "Devbox id where command was executed." }, "execution_id": { "type": "string", "description": "Ephemeral id of the execution in progress." }, "status": { "$ref": "#/components/schemas/DevboxExecutionStatus", "description": "Current status of the execution." }, "shell_name": { "description": "Shell name.", "type": ["string", "null"] }, "stdout": { "description": "Standard out generated by command. This field will remain unset until the execution has completed.", "type": ["string", "null"] }, "stderr": { "description": "Standard error generated by command. This field will remain unset until the execution has completed.", "type": ["string", "null"] }, "exit_status": { "format": "int32", "description": "Exit code of command execution. This field will remain unset until the execution has completed.", "type": ["integer", "null"] }, "stdout_truncated": { "description": "Indicates whether the stdout was truncated due to size limits.", "type": ["boolean", "null"] }, "stderr_truncated": { "description": "Indicates whether the stderr was truncated due to size limits.", "type": ["boolean", "null"] } }, "required": ["devbox_id", "execution_id", "status"] }, "DevboxCapabilities": { "type": "string", "enum": ["unknown", "docker_in_docker"] }, "DevboxCreateExecutionParameters": { "type": "object", "properties": { "command": { "type": "string", "description": "The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell." }, "shell_name": { "description": "The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.", "type": ["string", "null"] }, "attach_stdin": { "description": "Whether to attach stdin streaming for async commands. Not valid for execute_sync endpoint. Defaults to false if not specified.", "type": ["boolean", "null"] } }, "required": ["command"] }, "DevboxCreateParameters": { "type": "object", "properties": { "name": { "description": "(Optional) A user specified name to give the Devbox.", "type": ["string", "null"] }, "environment_variables": { "additionalProperties": { "type": "string" }, "description": "(Optional) Environment variables used to configure your Devbox.", "type": ["object", "null"] }, "secrets": { "additionalProperties": { "type": "string" }, "description": "(Optional) Map of environment variable names to secret names. The secret values will be securely injected as environment variables in the Devbox. Example: {\"DB_PASS\": \"DATABASE_PASSWORD\"} sets environment variable 'DB_PASS' to the value of secret 'DATABASE_PASSWORD'.", "type": ["object", "null"] }, "file_mounts": { "additionalProperties": { "type": "string" }, "description": "Map of paths and file contents to write before setup. Use mounts instead.", "type": ["object", "null"] }, "entrypoint": { "description": "(Optional) When specified, the Devbox will run this script as its main executable. The devbox lifecycle will be bound to entrypoint, shutting down when the process is complete.", "type": ["string", "null"] }, "blueprint_id": { "description": "Blueprint ID to use for the Devbox. If none set, the Devbox will be created with the default Runloop Devbox image. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.", "type": ["string", "null"] }, "blueprint_name": { "description": "Name of Blueprint to use for the Devbox. When set, this will load the latest successfully built Blueprint with the given name. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.", "type": ["string", "null"] }, "launch_parameters": { "description": "Parameters to configure the resources and launch time behavior of the Devbox.", "anyOf": [ { "$ref": "#/components/schemas/LaunchParameters" }, { "type": "null" } ] }, "snapshot_id": { "description": "Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.", "type": ["string", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to attach to the devbox for organization.", "type": ["object", "null"] }, "code_mounts": { "items": { "$ref": "#/components/schemas/CodeMountParameters" }, "description": "A list of code mounts to be included in the Devbox. Use mounts instead.", "type": ["array", "null"] }, "mounts": { "items": { "$ref": "#/components/schemas/Mount" }, "description": "A list of mounts to be included in the Devbox.", "type": ["array", "null"] }, "tunnel": { "description": "(Optional) Configuration for creating a V2 tunnel at Devbox launch time. When specified, a tunnel will be automatically provisioned and the tunnel details will be included in the Devbox response.", "anyOf": [ { "$ref": "#/components/schemas/TunnelConfig" }, { "type": "null" } ] }, "gateways": { "additionalProperties": { "$ref": "#/components/schemas/GatewaySpec" }, "description": "(Optional) Agent gateway specifications for credential proxying. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC'). The agent gateway will proxy requests to external APIs using the specified credential without exposing the real API key. Example: {'GWS_ANTHROPIC': {'gateway': 'anthropic', 'secret': 'my_claude_key'}}", "type": ["object", "null"] }, "mcp": { "additionalProperties": { "$ref": "#/components/schemas/McpSpec" }, "description": "[Beta] (Optional) MCP specifications for MCP server access. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret. The devbox will also receive RL_MCP_URL for the MCP hub endpoint. Example: {'MCP_SECRET': {'mcp_config': 'github-readonly', 'secret': 'MY_GITHUB_TOKEN'}}", "type": ["object", "null"] } } }, "DevboxCreateSshKeyView": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the Devbox." }, "url": { "type": "string", "description": "The host url of the Devbox that can be used for SSH." }, "ssh_private_key": { "type": "string", "description": "The ssh private key, in PEM format." }, "ssh_user": { "type": "string", "description": "The Linux user to use for SSH connections to this Devbox." } }, "required": ["id", "url", "ssh_private_key", "ssh_user"] }, "DevboxDiskSnapshotListView": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxDiskSnapshotView" }, "description": "List of snapshots matching filter." }, "has_more": { "type": "boolean" }, "total_count": { "format": "int32", "type": ["integer", "null"] } }, "required": ["snapshots", "has_more"] }, "DevboxDiskSnapshotView": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the snapshot." }, "name": { "description": "(Optional) The custom name of the snapshot.", "type": ["string", "null"] }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the Snapshot (Unix timestamp milliseconds)." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "User defined metadata associated with the snapshot." }, "source_devbox_id": { "type": "string", "description": "The source Devbox ID this snapshot was created from." }, "source_blueprint_id": { "description": "(Optional) The source Blueprint ID this snapshot was created from.", "type": ["string", "null"] }, "commit_message": { "description": "(Optional) The commit message of the snapshot (max 1000 characters).", "type": ["string", "null"] }, "size_bytes": { "format": "int64", "description": "(Optional) The size of the snapshot in bytes, relative to the base blueprint.", "type": ["integer", "null"] } }, "required": ["id", "create_time_ms", "metadata", "source_devbox_id"] }, "DevboxDownloadFileParameters": { "type": "object", "properties": { "path": { "type": "string", "description": "The path on the Devbox filesystem to read the file from. Path is relative to user home directory." } }, "required": ["path"] }, "DevboxEvictionEventView": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "The ID of the Devbox with a pending eviction." }, "eviction_deadline_ms": { "type": "integer", "format": "int64", "description": "Unix timestamp (milliseconds) after which the Devbox will be suspended. Advisory and best-effort." } }, "required": ["devbox_id", "eviction_deadline_ms"] }, "DevboxExecutionDetailView": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "Devbox id where command was executed." }, "stdout": { "type": "string", "description": "Standard out generated by command." }, "stderr": { "type": "string", "description": "Standard error generated by command." }, "exit_status": { "type": "integer", "format": "int32", "description": "Exit status of command execution." }, "shell_name": { "description": "Shell name.", "type": ["string", "null"] } }, "required": ["devbox_id", "stdout", "stderr", "exit_status"] }, "DevboxExecutionStatus": { "type": "string", "enum": ["queued", "running", "completed"] }, "DevboxKillExecutionRequest": { "type": "object", "properties": { "kill_process_group": { "description": "Whether to kill the entire process group (default: false). If true, kills all processes in the same process group as the target process.", "type": ["boolean", "null"] } } }, "DevboxListView": { "type": "object", "properties": { "devboxes": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxView" }, "description": "List of devboxes matching filter." }, "has_more": { "type": "boolean" }, "total_count": { "format": "int32", "type": ["integer", "null"] } }, "required": ["devboxes", "has_more"] }, "DevboxLog": { "type": "object", "properties": { "cmd_id": { "description": "Identifier of the associated command the log is sourced from.", "type": ["string", "null"] }, "level": { "type": "string", "description": "Log line severity level." }, "timestamp_ms": { "type": "integer", "format": "int64", "description": "Time of log (Unix timestamp milliseconds)." }, "shell_name": { "description": "The Shell name the cmd executed in.", "type": ["string", "null"] }, "cmd": { "description": "The Command Executed", "type": ["string", "null"] }, "message": { "description": "Log line message.", "type": ["string", "null"] }, "exit_code": { "format": "int32", "description": "The Exit Code of the command", "type": ["integer", "null"] }, "source": { "$ref": "#/components/schemas/DevboxLogSource", "description": "The source of the log." } }, "required": ["level", "timestamp_ms", "source"] }, "DevboxLogSource": { "type": "string", "enum": [ "setup_commands", "entrypoint", "exec", "files", "stats", "kmsg" ] }, "DevboxLogsListView": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxLog" }, "description": "List of logs for the given devbox." } }, "required": ["logs"] }, "DevboxReadFileParameters": { "type": "object", "properties": { "file_path": { "type": "string", "description": "The path on the Devbox filesystem to read the file from. Path is relative to user home directory." } }, "required": ["file_path"] }, "DevboxResourceUsageView": { "type": "object", "properties": { "id": { "type": "string", "description": "The devbox ID." }, "total_active_seconds": { "type": "integer", "format": "int64", "description": "Total time in seconds the devbox was actively running (excludes time spent suspended)." }, "total_elapsed_seconds": { "type": "integer", "format": "int64", "description": "Total elapsed time in seconds from devbox creation to now (or end time if terminated). Includes all time regardless of devbox state." }, "vcpu_seconds": { "type": "integer", "format": "int64", "description": "vCPU usage in vCPU-seconds (total_active_seconds multiplied by the number of vCPUs)." }, "memory_gb_seconds": { "type": "integer", "format": "int64", "description": "Memory usage in GB-seconds (total_active_seconds multiplied by memory in GB)." }, "disk_gb_seconds": { "type": "integer", "format": "int64", "description": "Disk usage in GB-seconds (total_elapsed_seconds multiplied by disk size in GB). Disk is billed for elapsed time since storage is consumed even when suspended." }, "start_time_ms": { "type": "integer", "format": "int64", "description": "The devbox creation time in milliseconds since epoch." }, "end_time_ms": { "format": "int64", "description": "The devbox end time in milliseconds since epoch, or null if still running.", "type": ["integer", "null"] }, "status": { "type": "string", "description": "The current status of the devbox." } }, "required": [ "id", "total_active_seconds", "total_elapsed_seconds", "vcpu_seconds", "memory_gb_seconds", "disk_gb_seconds", "start_time_ms", "status" ] }, "DevboxSendStdInRequest": { "type": "object", "properties": { "text": { "description": "Text to send to std in of the running execution.", "type": ["string", "null"] }, "signal": { "description": "Signal to send to std in of the running execution.", "anyOf": [ { "$ref": "#/components/schemas/SignalType" }, { "type": "null" } ] } } }, "DevboxSendStdInResult": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "Devbox id where command is executing." }, "execution_id": { "type": "string", "description": "Execution id that received the stdin." }, "success": { "type": "boolean", "description": "Whether the stdin was successfully sent." } }, "required": ["devbox_id", "execution_id", "success"] }, "DevboxSnapshotAsyncStatusView": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/DevboxSnapshotStatus", "description": "The current status of the snapshot operation." }, "snapshot": { "description": "The snapshot details if the operation completed successfully.", "anyOf": [ { "$ref": "#/components/schemas/DevboxDiskSnapshotView" }, { "type": "null" } ] }, "error_message": { "description": "Error message if the operation failed.", "type": ["string", "null"] } }, "required": ["status"] }, "DevboxSnapshotRequest": { "type": "object", "properties": { "name": { "description": "(Optional) A user specified name to give the snapshot", "type": ["string", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "(Optional) Metadata used to describe the snapshot", "type": ["object", "null"] }, "commit_message": { "description": "(Optional) Commit message associated with the snapshot (max 1000 characters)", "type": ["string", "null"] } } }, "DevboxSnapshotStatus": { "type": "string", "enum": ["in_progress", "error", "complete", "deleted"] }, "DevboxStartExecutionParameters": { "type": "object", "properties": { "command_id": { "type": "string", "description": "The command ID in UUIDv7 string format for idempotency and tracking" }, "command": { "type": "string", "description": "The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell." }, "shell_name": { "description": "The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.", "type": ["string", "null"] }, "optimistic_timeout": { "format": "int32", "description": "Timeout in seconds to wait for command completion, up to 25 seconds. Defaults to 25 seconds. Operation is not killed.", "type": ["integer", "null"] } }, "required": ["command_id", "command"] }, "DevboxStateTransition": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/DevboxViewStatus" }, "transition_time_ms": { "$ref": "#/components/schemas/Number", "description": "The time the status change occurred" }, "failure_reason": { "description": "The failure that caused this state transition, if applicable.", "type": ["string", "null"] } } }, "DevboxUpdateParameters": { "type": "object", "properties": { "name": { "description": "A user specified name to give the Devbox. Omit to leave unchanged or set to an empty string to clear it.", "type": ["string", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to replace the Devbox metadata. Omit to leave unchanged or set to an empty map to clear it.", "type": ["object", "null"] } } }, "DevboxView": { "type": "object", "description": "A Devbox represents a virtual development environment. It is an isolated sandbox that can be given to agents and used to run arbitrary code such as AI generated code.", "properties": { "id": { "type": "string", "description": "The ID of the Devbox." }, "name": { "description": "The name of the Devbox.", "type": ["string", "null"] }, "status": { "$ref": "#/components/schemas/DevboxViewStatus", "description": "The current status of the Devbox." }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the Devbox (Unix timestamp milliseconds)." }, "end_time_ms": { "format": "int64", "description": "The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.", "type": ["integer", "null"] }, "initiator_type": { "$ref": "#/components/schemas/InitiatorType", "description": "The type of initiator that created the Devbox." }, "initiator_id": { "description": "The ID of the initiator that created the Devbox.", "type": ["string", "null"] }, "blueprint_id": { "description": "The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.", "type": ["string", "null"] }, "snapshot_id": { "description": "The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.", "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The user defined Devbox metadata." }, "failure_reason": { "description": "The failure reason if the Devbox failed, if the Devbox has a 'failure' status.", "anyOf": [ { "$ref": "#/components/schemas/DevboxViewFailureReason" }, { "type": "null" } ] }, "shutdown_reason": { "description": "The shutdown reason if the Devbox shutdown, if the Devbox has a 'shutdown' status.", "anyOf": [ { "$ref": "#/components/schemas/DevboxViewShutdownReason" }, { "type": "null" } ] }, "launch_parameters": { "$ref": "#/components/schemas/LaunchParameters", "description": "The launch parameters used to create the Devbox." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxCapabilities" }, "description": "A list of capability groups this devbox has access to." }, "state_transitions": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxStateTransition" }, "description": "A list of state transitions in order with durations" }, "tunnel": { "description": "V2 tunnel information if a tunnel was created at launch time or via the createTunnel API.", "anyOf": [ { "$ref": "#/components/schemas/TunnelView" }, { "type": "null" } ] }, "gateway_specs": { "additionalProperties": { "$ref": "#/components/schemas/GatewaySpecView" }, "description": "Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').", "type": ["object", "null"] }, "mcp_specs": { "additionalProperties": { "$ref": "#/components/schemas/McpSpecView" }, "description": "[Beta] MCP specifications configured for this devbox. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret for MCP server access through the MCP hub.", "type": ["object", "null"] } }, "required": [ "id", "status", "create_time_ms", "end_time_ms", "metadata", "launch_parameters", "capabilities", "state_transitions" ] }, "DevboxViewFailureReason": { "type": "string", "enum": [ "out_of_memory", "out_of_disk", "execution_failed", "health_check_failed" ], "description": "The category of failure experienced by the Devbox.\n\nout_of_memory: The Devbox ran out of memory at runtime. Use launch parameters to request a larger resource size.\nout_of_disk: The Devbox ran out of disk at runtime. Please reach out to support for us to better support your use case.\nexecution_failed: The Devbox failed at runtime. Please use the dashboard to look at the logs of the failure.\nhealth_check_failed: The Devbox failed its health checks. This may indicate resource utilization is close to the maximum. Consider requesting a larger resource size.\n", "x-enum-descriptions": { "out_of_memory": "The Devbox ran out of memory at runtime. Use launch parameters to request a larger resource size.", "out_of_disk": "The Devbox ran out of disk at runtime. Please reach out to support for us to better support your use case.", "execution_failed": "The Devbox failed at runtime. Please use the dashboard to look at the logs of the failure.", "health_check_failed": "The Devbox failed its health checks. This may indicate resource utilization is close to the maximum. Consider requesting a larger resource size." } }, "DevboxViewShutdownReason": { "type": "string", "enum": [ "api_shutdown", "keep_alive_timeout", "entrypoint_exit", "idle", "ttl_expired" ], "description": "The reason that caused the transition of the Devbox to the shutown state.\n\napi_shutdown: The Devbox shutdown due to API request.\nentrypoint_exit: The Devbox entrypoint program completed.\nidle: The Devbox shutdown due to configured action on idle configuration.\nttl_expired: The Devbox shutdown due to TTL expiration.\n", "x-enum-descriptions": { "api_shutdown": "The Devbox shutdown due to API request.", "entrypoint_exit": "The Devbox entrypoint program completed.", "idle": "The Devbox shutdown due to configured action on idle configuration.", "ttl_expired": "The Devbox shutdown due to TTL expiration." } }, "DevboxViewStatus": { "type": "string", "enum": [ "scheduled", "queued", "provisioning", "initializing", "running", "suspending", "suspended", "resuming", "failure", "shutdown" ], "description": "The status of the Devbox.\n\nscheduled: Deprecated. The Devbox is waiting for infrastructure allocation to start. Use queued.\nqueued: The Devbox is waiting for infrastructure allocation to start.\nprovisioning: Runloop is allocating and booting the necessary infrastructure resources.\ninitializing: Runloop defined boot scripts are running to enable the environment for interaction.\nrunning: The Devbox is ready for interaction.\nsuspending: The Devbox disk is being snapshotted as part of suspension.\nsuspended: The Devbox disk is saved and no more active compute is being used for the Devbox.\nresuming: The Devbox disk is being loaded as part of booting a suspended Devbox.\nfailure: The Devbox failed as part of booting or running user requested actions.\nshutdown: The Devbox was successfully shutdown and no more active compute is being used.\n", "x-enum-descriptions": { "scheduled": "Deprecated. The Devbox is waiting for infrastructure allocation to start. Use queued.", "queued": "The Devbox is waiting for infrastructure allocation to start.", "provisioning": "Runloop is allocating and booting the necessary infrastructure resources.", "initializing": "Runloop defined boot scripts are running to enable the environment for interaction.", "running": "The Devbox is ready for interaction.", "suspending": "The Devbox disk is being snapshotted as part of suspension.", "suspended": "The Devbox disk is saved and no more active compute is being used for the Devbox.", "resuming": "The Devbox disk is being loaded as part of booting a suspended Devbox.", "failure": "The Devbox failed as part of booting or running user requested actions.", "shutdown": "The Devbox was successfully shutdown and no more active compute is being used." } }, "DevboxWaitForCommandRequest": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxExecutionStatus" }, "description": "The command execution statuses to wait for. At least one status must be provided. The command will be returned as soon as it reaches any of the provided statuses." }, "timeout_seconds": { "format": "int32", "description": "(Optional) Timeout in seconds to wait for the status, up to 25 seconds. Defaults to 25 seconds.", "type": ["integer", "null"] } }, "required": ["statuses"] }, "DevboxWaitForStatusRequest": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/DevboxViewStatus" }, "description": "The Devbox statuses to wait for. At least one status must be provided. The devbox will be returned as soon as it reaches any of the provided statuses." }, "timeout_seconds": { "format": "int32", "description": "(Optional) Timeout in seconds to wait for the status, up to 30 seconds. Defaults to 10 seconds.", "type": ["integer", "null"] } }, "required": ["statuses"] }, "DevboxWriteFileParameters": { "type": "object", "properties": { "file_path": { "type": "string", "description": "The path to write the file to on the Devbox. Path is relative to user home directory." }, "contents": { "type": "string", "description": "The UTF-8 string contents to write to the file." } }, "required": ["file_path", "contents"] }, "EgressRulesView": { "type": "object", "description": "Egress (outbound) network rules for a NetworkPolicy.", "properties": { "allow_all": { "type": "boolean", "description": "If true, all egress traffic is allowed and other fields are ignored. Used for ALLOW_ALL policies." }, "allow_devbox_to_devbox": { "type": "boolean", "description": "If true, allows traffic between the account's own devboxes via tunnels." }, "allowed_hostnames": { "type": "array", "items": { "type": "string" }, "description": "DNS-based allow list with wildcard support. Examples: ['github.com', '*.npmjs.org', 'api.openai.com']. Empty list with allow_all=false means no network access (DENY_ALL behavior)." }, "allowed_cidrs": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedCidr" }, "description": "CIDR-based allow list with optional port restrictions, additive with allowed_hostnames." }, "allow_agent_gateway": { "type": "boolean", "description": "If true, allows devbox egress to the agent gateway for credential proxying." }, "allow_mcp_gateway": { "type": "boolean", "description": "If true, allows devbox egress to the MCP hub for MCP server access." }, "allow_runloop_mirrors": { "type": "boolean", "description": "If true, allows devbox egress to Runloop's package/image registry mirrors. Implicitly allowed when allow_all is true." } }, "required": [ "allow_all", "allow_devbox_to_devbox", "allowed_hostnames", "allowed_cidrs", "allow_agent_gateway", "allow_mcp_gateway", "allow_runloop_mirrors" ] }, "EmptyRecord": { "type": "object", "properties": {} }, "ExecUpdateChunkView": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int64", "description": "The byte offset of this chunk of log stream." }, "output": { "type": "string", "description": "The latest log stream chunk." } }, "required": ["output"] }, "FileMount": { "type": "object", "properties": { "target": { "type": "string", "description": "Target path where the file should be mounted." }, "content": { "type": "string", "description": "Content of the file to mount." }, "type": { "type": "string", "enum": ["file_mount"], "default": "file_mount" } }, "required": ["target", "content", "type"] }, "FileUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "path": { "type": "string", "description": "The path to write the file to on the Devbox. Path is relative to user home directory." } }, "required": ["path"] }, "GatewayConfigCreateParameters": { "type": "object", "description": "Parameters required to create a new GatewayConfig.", "properties": { "name": { "type": "string", "description": "The human-readable name for the GatewayConfig. Names are labels and may be reused." }, "endpoint": { "type": "string", "description": "The target endpoint URL (e.g., 'https://api.anthropic.com')." }, "auth_mechanism": { "$ref": "#/components/schemas/AuthMechanismView", "description": "How credentials should be applied to proxied requests. Specify the type ('header', 'bearer') and optional key field." }, "description": { "description": "Optional description for this gateway configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "Additional headers applied to proxied requests after the auth mechanism. At most 8 entries.", "type": ["array", "null"] } }, "required": ["name", "endpoint", "auth_mechanism"] }, "GatewayConfigListView": { "type": "object", "description": "A paginated list of GatewayConfigs.", "properties": { "gateway_configs": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayConfigView" }, "description": "The list of GatewayConfigs." }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond this page." }, "total_count": { "format": "int32", "description": "Total count of GatewayConfigs that match the query.", "type": ["integer", "null"] } }, "required": ["gateway_configs", "has_more"] }, "GatewayConfigUpdateParameters": { "type": "object", "description": "Parameters for updating an existing GatewayConfig. All fields are optional - only specified fields will be updated.", "properties": { "name": { "description": "New name for the GatewayConfig. Names are labels and may be reused.", "type": ["string", "null"] }, "endpoint": { "description": "New target endpoint URL (e.g., 'https://api.anthropic.com').", "type": ["string", "null"] }, "auth_mechanism": { "description": "New authentication mechanism for applying credentials to proxied requests.", "anyOf": [ { "$ref": "#/components/schemas/AuthMechanismView" }, { "type": "null" } ] }, "description": { "description": "New description for this gateway configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.", "type": ["array", "null"] } } }, "GatewayConfigView": { "type": "object", "description": "A GatewayConfig defines a configuration for proxying API requests through the agent gateway. It specifies the target endpoint and how credentials should be applied.", "properties": { "id": { "type": "string", "description": "The unique identifier of the GatewayConfig." }, "account_id": { "description": "The account ID that owns this config.", "type": ["string", "null"] }, "name": { "type": "string", "description": "The human-readable name of the GatewayConfig. Names may be reused." }, "endpoint": { "type": "string", "description": "The target endpoint URL (e.g., 'https://api.anthropic.com')." }, "auth_mechanism": { "$ref": "#/components/schemas/AuthMechanismView", "description": "How credentials should be applied to proxied requests." }, "description": { "description": "Optional description for this gateway configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "Additional headers applied to proxied requests after the auth mechanism. Secret-backed entries reference the secret by 'sec_' id; values are never returned.", "type": ["array", "null"] }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the GatewayConfig (Unix timestamp in milliseconds)." } }, "required": [ "id", "name", "endpoint", "auth_mechanism", "create_time_ms" ] }, "GatewaySpec": { "type": "object", "description": "GatewaySpec links an agent gateway configuration to a secret for credential proxying in a devbox. The agent gateway will proxy requests to external APIs using the specified credential without exposing the real API key.", "properties": { "gateway": { "type": "string", "description": "The gateway config to use. Can be a gateway config ID (gwc_xxx) or name. A name binds the most recently created config with that name." }, "secret": { "type": "string", "description": "The secret containing the credential. Can be a secret ID or name." } }, "required": ["gateway", "secret"] }, "GatewaySpecView": { "type": "object", "properties": { "gateway_config_id": { "type": "string", "description": "The ID of the gateway config (e.g., gwc_123abc)." }, "secret_id": { "type": "string", "description": "The ID of the secret containing the credential." } }, "required": ["gateway_config_id", "secret_id"] }, "GatewayTokenCreateParameters": { "type": "object", "description": "Parameters for minting an agent gateway token for a Devbox. The token lets the Devbox call the API described by the gateway config using the supplied credential, without ever receiving the credential itself.", "properties": { "gateway": { "type": "string", "description": "The gateway config to use. Can be a gateway config ID (gwc_xxx) or name." }, "secret": { "type": "string", "description": "The secret containing the credential. Can be a secret ID or name." } }, "required": ["gateway", "secret"] }, "GatewayTokenView": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "The Devbox the token is bound to." }, "gateway_config_id": { "type": "string", "description": "The ID of the gateway config the token proxies through." }, "token": { "type": "string", "description": "The token to send to the gateway as a Bearer token in the Authorization header. Only accepted for requests originating from the bound Devbox." }, "url": { "type": "string", "description": "The gateway URL to send requests to. Matches the value of the {prefix}_URL environment variable inside the Devbox." }, "endpoint": { "type": "string", "description": "The target API endpoint the gateway proxies to." }, "auth_mechanism": { "$ref": "#/components/schemas/AuthMechanismView", "description": "How the gateway applies the credential to proxied requests." } }, "required": [ "devbox_id", "gateway_config_id", "token", "url", "endpoint", "auth_mechanism" ] }, "GitSource": { "type": "object", "description": "Git-based agent source configuration.", "properties": { "repository": { "type": "string", "description": "Git repository URL" }, "ref": { "description": "Optional Git ref (branch/tag/commit), defaults to main/HEAD", "type": ["string", "null"] }, "agent_setup": { "items": { "type": "string" }, "description": "Setup commands to run after cloning", "type": ["array", "null"] } }, "required": ["repository"] }, "IdleAction": { "type": "string", "enum": ["shutdown", "suspend"], "description": "Action to take after Devbox idle timer is triggered.\n\nshutdown: Shutdown the Devbox.\nsuspend: Suspend the Devbox.\n", "x-enum-descriptions": { "shutdown": "Shutdown the Devbox.", "suspend": "Suspend the Devbox." } }, "IdleConfigurationParameters": { "type": "object", "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"] }, "InitiatorType": { "type": "string", "enum": ["unknown", "api", "reflex"] }, "LaunchParameters": { "type": "object", "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": { "items": { "type": "string" }, "description": "Set of commands to be run at launch time, before the entrypoint process is run.", "type": ["array", "null"] }, "resource_size_request": { "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.", "anyOf": [ { "$ref": "#/components/schemas/ResourceSize" }, { "type": "null" } ] }, "available_ports": { "items": { "type": "integer", "format": "int32" }, "description": "[Deprecated] A list of ports to make available on the Devbox. This field is ignored.", "type": ["array", "null"] }, "keep_alive_time_seconds": { "format": "int64", "description": "Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).", "type": ["integer", "null"] }, "after_idle": { "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.", "anyOf": [ { "$ref": "#/components/schemas/IdleConfigurationParameters" }, { "type": "null" } ] }, "custom_cpu_cores": { "format": "double", "description": "Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.", "type": ["number", "null"] }, "custom_gb_memory": { "format": "int32", "description": "Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.", "type": ["integer", "null"] }, "custom_disk_size": { "format": "int32", "description": "Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.", "type": ["integer", "null"] }, "architecture": { "description": "The target architecture for the Devbox. If unset, defaults to x86_64.", "anyOf": [ { "$ref": "#/components/schemas/Architecture" }, { "type": "null" } ] }, "user_parameters": { "description": "Specify the user for execution on Devbox. If not set, default `user` will be used.", "anyOf": [ { "$ref": "#/components/schemas/UserParameters" }, { "type": "null" } ] }, "required_services": { "items": { "type": "string" }, "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.", "type": ["array", "null"] }, "network_policy_id": { "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.", "type": ["string", "null"] }, "lifecycle": { "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), resume triggers via lifecycle.resume_triggers, and optional lifecycle hooks via lifecycle.lifecycle_hooks.", "anyOf": [ { "$ref": "#/components/schemas/LifecycleConfigurationParameters" }, { "type": "null" } ] }, "provisioning_tier": { "description": "(Optional, Alpha) standard is default and flex is lazily provisioned and may be pre-empted. This is an alpha feature and its behavior may change without notice.", "anyOf": [ { "$ref": "#/components/schemas/ProvisioningTier" }, { "type": "null" } ] } } }, "LifecycleConfigurationParameters": { "type": "object", "description": "Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.", "properties": { "after_idle": { "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.", "anyOf": [ { "$ref": "#/components/schemas/IdleConfigurationParameters" }, { "type": "null" } ] }, "resume_triggers": { "description": "Triggers that can resume a suspended Devbox.", "anyOf": [ { "$ref": "#/components/schemas/ResumeTriggers" }, { "type": "null" } ] }, "lifecycle_hooks": { "description": "Optional lifecycle hooks. suspend_commands run through the suspend path before the Devbox suspends; see launch_commands for work on every startup.", "anyOf": [ { "$ref": "#/components/schemas/LifecycleHooks" }, { "type": "null" } ] } } }, "LifecycleHooks": { "type": "object", "description": "Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.", "properties": { "suspend_commands": { "items": { "type": "string" }, "description": "Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons).", "type": ["array", "null"] }, "suspend_deadline_ms": { "format": "int64", "description": "Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM.", "type": ["integer", "null"] } } }, "McpConfigCreateParameters": { "type": "object", "description": "Parameters required to create a new McpConfig.", "properties": { "name": { "type": "string", "description": "The human-readable name for the McpConfig. Names are labels and may be reused. The first segment before '-' is used as the service name for tool routing (e.g., 'github-readonly' uses 'github' as the service name)." }, "endpoint": { "type": "string", "description": "The target MCP server endpoint URL (e.g., 'https://mcp.example.com')." }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns specifying which tools are allowed from this MCP server. Examples: ['*'] for all tools, ['github.search_*', 'github.get_*'] for specific patterns." }, "description": { "description": "Optional description for this MCP configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "Additional headers applied to upstream requests after the credential. At most 8 entries.", "type": ["array", "null"] }, "auth_mechanism": { "description": "How the primary credential is applied to upstream requests. Defaults to 'bearer'.", "anyOf": [ { "$ref": "#/components/schemas/AuthMechanismView" }, { "type": "null" } ] } }, "required": ["name", "endpoint", "allowed_tools"] }, "McpConfigListView": { "type": "object", "description": "A paginated list of McpConfigs.", "properties": { "mcp_configs": { "type": "array", "items": { "$ref": "#/components/schemas/McpConfigView" }, "description": "The list of McpConfigs." }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond this page." }, "total_count": { "format": "int32", "description": "Total count of McpConfigs that match the query.", "type": ["integer", "null"] } }, "required": ["mcp_configs", "has_more"] }, "McpConfigUpdateParameters": { "type": "object", "description": "Parameters for updating an existing McpConfig. All fields are optional - only specified fields will be updated.", "properties": { "name": { "description": "New name for the McpConfig. Names are labels and may be reused.", "type": ["string", "null"] }, "endpoint": { "description": "New target MCP server endpoint URL.", "type": ["string", "null"] }, "allowed_tools": { "items": { "type": "string" }, "description": "New glob patterns specifying which tools are allowed. Examples: ['*'] for all tools, ['github.search_*'] for specific patterns.", "type": ["array", "null"] }, "description": { "description": "New description for this MCP configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.", "type": ["array", "null"] }, "auth_mechanism": { "description": "New auth mechanism for the primary credential.", "anyOf": [ { "$ref": "#/components/schemas/AuthMechanismView" }, { "type": "null" } ] } } }, "McpConfigView": { "type": "object", "description": "An McpConfig defines a configuration for connecting to an upstream MCP (Model Context Protocol) server. It specifies the target endpoint and which tools are allowed.", "properties": { "id": { "type": "string", "description": "The unique identifier of the McpConfig." }, "name": { "type": "string", "description": "The human-readable name of the McpConfig. Names may be reused." }, "endpoint": { "type": "string", "description": "The target MCP server endpoint URL (e.g., 'https://mcp.example.com')." }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns specifying which tools are allowed from this MCP server (e.g., ['github.search_*', 'github.get_*'] or ['*'] for all tools)." }, "description": { "description": "Optional description for this MCP configuration.", "type": ["string", "null"] }, "custom_headers": { "items": { "$ref": "#/components/schemas/CustomHeaderView" }, "description": "Additional headers applied to upstream requests after the credential. Secret-backed entries reference the secret by 'sec_' id; values are never returned.", "type": ["array", "null"] }, "auth_mechanism": { "$ref": "#/components/schemas/AuthMechanismView", "description": "How the primary credential is applied to upstream requests." }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the McpConfig (Unix timestamp in milliseconds)." } }, "required": [ "id", "name", "endpoint", "allowed_tools", "auth_mechanism", "create_time_ms" ] }, "McpSpec": { "type": "object", "description": "[Beta] McpSpec links an MCP configuration to a secret for MCP server access in a devbox. The MCP hub will proxy requests to upstream MCP servers using the specified credential, with tool-level access control based on the MCP config's allowed_tools.", "properties": { "mcp_config": { "type": "string", "description": "The MCP config to use. Can be an MCP config ID (mcp_xxx) or name. A name binds the most recently created config with that name." }, "secret": { "type": "string", "description": "The secret containing the MCP server credential. Can be a secret ID or name." } }, "required": ["mcp_config", "secret"] }, "McpSpecView": { "type": "object", "properties": { "mcp_config_id": { "type": "string", "description": "The ID of the MCP config (e.g., mcp_123abc)." }, "secret_id": { "type": "string", "description": "The ID of the secret containing the credential." } }, "required": ["mcp_config_id", "secret_id"] }, "McpTokenCreateParameters": { "type": "object", "description": "[Beta] Parameters for minting an MCP token for a Devbox. The token grants the Devbox access to the upstream MCP server described by the MCP config, using the supplied credential, with tool-level access control based on the config's allowed_tools.", "properties": { "mcp_config": { "type": "string", "description": "The MCP config to use. Can be an MCP config ID (mcp_xxx) or name." }, "secret": { "type": "string", "description": "The secret containing the MCP server credential. Can be a secret ID or name." } }, "required": ["mcp_config", "secret"] }, "McpTokenView": { "type": "object", "properties": { "devbox_id": { "type": "string", "description": "The Devbox the token is bound to." }, "mcp_config_id": { "type": "string", "description": "The ID of the MCP config the token grants access to." }, "token": { "type": "string", "description": "The token to send to the MCP hub as a Bearer token in the Authorization header. Only accepted for requests originating from the bound Devbox." }, "url": { "type": "string", "description": "The MCP hub URL the token authenticates against. Matches the RL_MCP_URL environment variable inside the Devbox." }, "endpoint": { "type": "string", "description": "The upstream MCP server endpoint the hub proxies to." }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns for the tools the token permits." } }, "required": [ "devbox_id", "mcp_config_id", "token", "url", "endpoint", "allowed_tools" ] }, "MetadataKeysView": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" } } } }, "MetadataValuesView": { "type": "object", "properties": { "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "Mount": { "oneOf": [ { "$ref": "#/components/schemas/ObjectMount" }, { "$ref": "#/components/schemas/AgentMount" }, { "$ref": "#/components/schemas/CodeMount" }, { "$ref": "#/components/schemas/FileMount" }, { "$ref": "#/components/schemas/BrokerMount" } ], "discriminator": { "propertyName": "type", "mapping": { "object_mount": "#/components/schemas/ObjectMount", "agent_mount": "#/components/schemas/AgentMount", "code_mount": "#/components/schemas/CodeMount", "file_mount": "#/components/schemas/FileMount", "broker_mount": "#/components/schemas/BrokerMount" } } }, "NetworkPolicyCreateParameters": { "type": "object", "description": "Parameters required to create a new NetworkPolicy.", "properties": { "name": { "type": "string", "description": "The human-readable name for the NetworkPolicy. Names are labels and may be reused." }, "description": { "description": "Optional description for the NetworkPolicy.", "type": ["string", "null"] }, "allow_all": { "description": "(Optional) If true, all egress traffic is allowed (ALLOW_ALL policy). Defaults to false.", "type": ["boolean", "null"] }, "allow_devbox_to_devbox": { "description": "(Optional) If true, allows traffic between the account's own devboxes via tunnels. Defaults to false. If allow_all is true, this is automatically set to true.", "type": ["boolean", "null"] }, "allowed_hostnames": { "items": { "type": "string" }, "description": "(Optional) DNS-based allow list with wildcard support. Examples: ['github.com', '*.npmjs.org'].", "type": ["array", "null"] }, "allowed_cidrs": { "items": { "$ref": "#/components/schemas/AllowedCidr" }, "description": "(Optional) IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames. Example: [{'cidr': '10.12.0.0/16', 'ports': [{'port': 443}]}].", "type": ["array", "null"] }, "allow_agent_gateway": { "description": "(Optional) If true, allows devbox egress to the agent gateway for credential proxying. Defaults to false.", "type": ["boolean", "null"] }, "allow_mcp_gateway": { "description": "(Optional) If true, allows devbox egress to the MCP hub for MCP server access. Defaults to false.", "type": ["boolean", "null"] }, "allow_runloop_mirrors": { "description": "(Optional) If true, allows devbox egress to Runloop's package/image registry mirrors. Defaults to false. Implicitly allowed when allow_all is true.", "type": ["boolean", "null"] } }, "required": ["name"] }, "NetworkPolicyListView": { "type": "object", "description": "A list of NetworkPolicies with pagination information.", "properties": { "network_policies": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkPolicyView" }, "description": "The list of NetworkPolicies." }, "has_more": { "type": "boolean", "description": "Whether there are more results available." }, "total_count": { "format": "int32", "description": "Total count of items in this response.", "type": ["integer", "null"] } }, "required": ["network_policies", "has_more"] }, "NetworkPolicyUpdateParameters": { "type": "object", "description": "Parameters for updating an existing NetworkPolicy. All fields are optional.", "properties": { "name": { "description": "Updated human-readable name for the NetworkPolicy.", "type": ["string", "null"] }, "description": { "description": "Updated description for the NetworkPolicy.", "type": ["string", "null"] }, "allow_all": { "description": "If true, all egress traffic is allowed (ALLOW_ALL policy).", "type": ["boolean", "null"] }, "allow_devbox_to_devbox": { "description": "If true, allows traffic between the account's own devboxes via tunnels.", "type": ["boolean", "null"] }, "allowed_hostnames": { "items": { "type": "string" }, "description": "Updated DNS-based allow list with wildcard support. Examples: ['github.com', '*.npmjs.org'].", "type": ["array", "null"] }, "allowed_cidrs": { "items": { "$ref": "#/components/schemas/AllowedCidr" }, "description": "Updated IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames.", "type": ["array", "null"] }, "allow_agent_gateway": { "description": "If true, allows devbox egress to the agent gateway.", "type": ["boolean", "null"] }, "allow_mcp_gateway": { "description": "If true, allows devbox egress to the MCP hub.", "type": ["boolean", "null"] }, "allow_runloop_mirrors": { "description": "If true, allows devbox egress to Runloop's package/image registry mirrors. Implicitly allowed when allow_all is true.", "type": ["boolean", "null"] } } }, "NetworkPolicyView": { "type": "object", "description": "A NetworkPolicy defines egress network access rules for devboxes. Policies can be applied to blueprints, devboxes, and snapshot resumes.", "properties": { "id": { "type": "string", "description": "The unique identifier of the NetworkPolicy." }, "name": { "type": "string", "description": "The human-readable name of the NetworkPolicy. Names may be reused." }, "description": { "description": "Optional description of the NetworkPolicy.", "type": ["string", "null"] }, "egress": { "$ref": "#/components/schemas/EgressRulesView", "description": "The egress rules for this policy." }, "create_time_ms": { "type": "integer", "format": "int64", "description": "The creation time of the NetworkPolicy (Unix timestamp in milliseconds)." }, "update_time_ms": { "type": "integer", "format": "int64", "description": "Last update time of the NetworkPolicy (Unix timestamp in milliseconds)." } }, "required": ["id", "name", "egress", "create_time_ms", "update_time_ms"] }, "NpmSource": { "type": "object", "description": "NPM-based agent source configuration.", "properties": { "package_name": { "type": "string", "description": "NPM package name" }, "registry_url": { "description": "NPM registry URL", "type": ["string", "null"] }, "agent_setup": { "items": { "type": "string" }, "description": "Setup commands to run after installation", "type": ["array", "null"] } }, "required": ["package_name"] }, "Number": { "type": "object", "properties": {} }, "ObjectContext": { "type": "object", "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"] }, "ObjectCreateParameters": { "type": "object", "description": "Parameters required to create a new Object.", "properties": { "name": { "type": "string", "description": "The name of the Object." }, "content_type": { "$ref": "#/components/schemas/ContentType", "description": "The content type of the Object." }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to attach to the object for organization.", "type": ["object", "null"] }, "ttl_ms": { "format": "int64", "description": "Optional lifetime of the object in milliseconds, after which the object is automatically deleted. Time starts ticking after the object is created.", "type": ["integer", "null"] } }, "required": ["name", "content_type"] }, "ObjectDownloadUrlView": { "type": "object", "description": "A response containing a presigned download URL for an Object.", "properties": { "download_url": { "type": "string", "description": "The presigned download URL for the Object." } }, "required": ["download_url"] }, "ObjectListView": { "type": "object", "description": "A paginated list of Objects.", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectView" }, "description": "List of Object entities." }, "has_more": { "type": "boolean", "description": "True if there are more results available beyond this page." }, "total_count": { "format": "int32", "description": "Total number of Objects across all pages.", "type": ["integer", "null"] } }, "required": ["objects", "has_more"] }, "ObjectMount": { "type": "object", "properties": { "object_id": { "type": "string", "description": "The ID of the object to write." }, "object_path": { "type": "string", "description": "The path to write the object on the Devbox. Use absolute path of object (ie /home/user/object.txt, or directory if archive /home/user/archive_dir)" }, "type": { "type": "string", "enum": ["object_mount"], "default": "object_mount" } }, "required": ["object_id", "object_path", "type"] }, "ObjectSource": { "type": "object", "description": "Object store agent source configuration.", "properties": { "object_id": { "type": "string", "description": "Object ID" }, "agent_setup": { "items": { "type": "string" }, "description": "Setup commands to run after unpacking", "type": ["array", "null"] } }, "required": ["object_id"] }, "ObjectState": { "type": "string", "enum": ["UPLOADING", "READ_ONLY", "DELETED", "ERROR"] }, "ObjectView": { "type": "object", "description": "An Object represents a stored data entity with metadata.", "properties": { "id": { "type": "string", "description": "The unique identifier of the Object." }, "name": { "type": "string", "description": "The name of the Object." }, "state": { "$ref": "#/components/schemas/ObjectState", "description": "The current state of the Object." }, "size_bytes": { "format": "int64", "description": "The size of the Object content in bytes (null until uploaded).", "type": ["integer", "null"] }, "content_type": { "$ref": "#/components/schemas/ContentType", "description": "The content type of the Object." }, "create_time_ms": { "type": "integer", "format": "int64", "description": "The creation time of the Object in milliseconds since epoch." }, "delete_after_time_ms": { "format": "int64", "description": "The time after which the Object will be deleted in milliseconds since epoch.", "type": ["integer", "null"] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "User defined metadata to attach to the Object for organization.", "type": ["object", "null"] }, "upload_url": { "description": "Presigned URL for uploading content with HTTP PUT (only present on create).", "type": ["string", "null"] }, "upload_headers": { "additionalProperties": { "type": "string" }, "description": "HTTP headers required when uploading to upload_url (only present when needed on create).", "type": ["object", "null"] } }, "required": ["id", "name", "state", "content_type", "create_time_ms"] }, "PipSource": { "type": "object", "description": "Pip-based agent source configuration.", "properties": { "package_name": { "type": "string", "description": "Pip package name" }, "registry_url": { "description": "Pip registry URL", "type": ["string", "null"] }, "agent_setup": { "items": { "type": "string" }, "description": "Setup commands to run after installation", "type": ["array", "null"] } }, "required": ["package_name"] }, "PortProtocol": { "type": "string", "enum": ["TCP", "UDP"], "description": "L4 protocol for a port rule." }, "PortRule": { "type": "object", "description": "A port or port range allowed for a CIDR egress rule.", "properties": { "port": { "type": "integer", "format": "int32", "description": "The allowed port (1-65535), or the start of a port range." }, "end_port": { "format": "int32", "description": "(Optional) Inclusive end of the port range (port-65535). Omit for a single port.", "type": ["integer", "null"] }, "protocol": { "description": "(Optional) 'TCP' or 'UDP'. Defaults to 'TCP'.", "anyOf": [ { "$ref": "#/components/schemas/PortProtocol" }, { "type": "null" } ] } }, "required": ["port"] }, "ProvisioningTier": { "type": "string", "enum": ["standard", "flex"] }, "PtyConnectView": { "type": "object", "properties": { "session_name": { "type": "string" }, "status": { "type": "string" }, "protocol_version": { "type": "string" }, "connect_url": { "type": "string" }, "created": { "type": "boolean" }, "attached": { "type": "boolean" }, "cols": { "type": "integer", "format": "int32" }, "rows": { "type": "integer", "format": "int32" }, "idle_ttl_seconds": { "type": "integer", "format": "int64" } }, "required": ["created", "attached"] }, "PtyControlAction": { "type": "string", "enum": ["resize", "signal", "close"] }, "PtyControlParameters": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/PtyControlAction" }, "cols": { "type": "integer", "format": "int32" }, "rows": { "type": "integer", "format": "int32" }, "signal": { "type": "string" } } }, "PtyControlResultView": { "type": "object", "properties": { "session_name": { "type": "string" }, "status": { "type": "string" } } }, "PtyTunnelView": { "type": "object", "description": "An ephemeral PTY tunnel providing authenticated terminal access to a Devbox. These tunnels are not stored on the Devbox and are generated fresh on each request. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai with X-Runloop-Tunnel-Authorization: Bearer {auth_token}.", "properties": { "tunnel_key": { "type": "string", "description": "The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}" }, "auth_token": { "type": "string", "description": "Bearer token for tunnel authentication. Always required for PTY tunnels. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}." } }, "required": ["tunnel_key", "auth_token"] }, "PublishEventOrigin": { "type": "string", "enum": ["EXTERNAL_EVENT", "AGENT_EVENT", "USER_EVENT"], "description": "Allowed event origins for publish requests." }, "PublishParams": { "type": "object", "properties": { "source": { "type": "string", "description": "The source of the event (e.g. github, slack)." }, "event_type": { "type": "string", "description": "The event type (e.g. push, pull_request)." }, "origin": { "$ref": "#/components/schemas/PublishEventOrigin", "description": "Event origin." }, "payload": { "type": "string", "description": "Event payload." } }, "required": ["source", "event_type", "origin", "payload"] }, "PublishResultView": { "type": "object", "properties": { "sequence": { "type": "integer", "format": "int64", "description": "Assigned sequence number." }, "timestamp_ms": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds since epoch." } }, "required": ["sequence", "timestamp_ms"] }, "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.\n\nX_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk\nSMALL: 1 cpu x 2GiB memory x 4GiB disk\nMEDIUM: 2 cpu x 4GiB memory x 8GiB disk\nLARGE: 2 cpu x 8GiB memory x 16GiB disk\nX_LARGE: 4 cpu x 16GiB memory x 16GiB disk\nXX_LARGE: 8 cpu x 32GiB memory x 16GiB disk\nCUSTOM_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.\n", "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." } }, "RestrictedKeyCreateParameters": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeEntryView" } }, "expires_at_ms": { "format": "int64", "type": ["integer", "null"] } } }, "RestrictedKeyCreatedView": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_secret": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeEntryView" } }, "expires_at_ms": { "format": "int64", "type": ["integer", "null"] } } }, "ResumeTriggers": { "type": "object", "description": "Triggers that can resume a suspended Devbox.", "properties": { "http": { "description": "When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.", "type": ["boolean", "null"] }, "axon_event": { "description": "When true, axon events targeting a suspended Devbox will trigger a resume.", "type": ["boolean", "null"] } } }, "ScopeEntryView": { "type": "object", "properties": { "resource_type": { "$ref": "#/components/schemas/ApiResourceType" }, "access_level": { "$ref": "#/components/schemas/ApiAccessLevel" } } }, "SecretCreateParameters": { "type": "object", "description": "Parameters required to create a new Secret.", "properties": { "name": { "type": "string", "description": "The name for the Secret. Must be a valid environment variable name (alphanumeric and underscores only). Example: 'DATABASE_PASSWORD'" }, "value": { "type": "string", "description": "The value to store for this Secret. This will be encrypted at rest and made available as an environment variable in Devboxes. Example: 'my-secure-password'" } }, "required": ["name", "value"] }, "SecretListView": { "type": "object", "description": "A paginated list of Secrets.", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretView" }, "description": "List of Secret objects. Values are omitted for security." }, "has_more": { "type": "boolean", "description": "True if there are more results available beyond this page." }, "total_count": { "format": "int32", "description": "Total number of Secrets across all pages.", "type": ["integer", "null"] } }, "required": ["secrets", "has_more"] }, "SecretUpdateParameters": { "type": "object", "description": "Parameters required to update an existing Secret.", "properties": { "value": { "type": "string", "description": "The new value for the Secret. This will replace the existing value and be encrypted at rest. Example: 'my-updated-secure-password'" } }, "required": ["value"] }, "SecretView": { "type": "object", "description": "A Secret represents a key-value pair that can be securely stored and used in Devboxes as environment variables.", "properties": { "id": { "type": "string", "description": "The unique identifier of the Secret." }, "name": { "type": "string", "description": "The name of the Secret. Used as the environment variable name in Devboxes." }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the Secret (Unix timestamp in milliseconds)." }, "update_time_ms": { "type": "integer", "format": "int64", "description": "Last update time of the Secret (Unix timestamp in milliseconds)." } }, "required": ["id", "name", "create_time_ms", "update_time_ms"] }, "SignalType": { "type": "string", "enum": ["EOF", "INTERRUPT"] }, "SqlBatchParams": { "type": "object", "properties": { "statements": { "type": "array", "items": { "$ref": "#/components/schemas/SqlStatementParams" }, "description": "The SQL statements to execute atomically within a transaction." } }, "required": ["statements"] }, "SqlBatchResultView": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SqlStepResultView" }, "description": "One result per statement, in order." } }, "required": ["results"] }, "SqlColumnMetaView": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name or alias." }, "type": { "type": "string", "description": "Declared type (TEXT, INTEGER, REAL, BLOB, or empty)." } }, "required": ["name", "type"] }, "SqlQueryResultView": { "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/SqlColumnMetaView" }, "description": "Column metadata." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Result rows (empty for non-SELECT statements)." }, "meta": { "$ref": "#/components/schemas/SqlResultMetaView", "description": "Execution metadata." } }, "required": ["columns", "rows", "meta"] }, "SqlResultMetaView": { "type": "object", "properties": { "duration_ms": { "type": "number", "format": "double", "description": "Execution time in milliseconds." }, "changes": { "type": "integer", "format": "int64", "description": "Rows modified by INSERT/UPDATE/DELETE." }, "rows_read_limit_reached": { "type": "boolean", "description": "True when result was truncated at the row limit." } }, "required": ["duration_ms", "changes", "rows_read_limit_reached"] }, "SqlStatementParams": { "type": "object", "properties": { "sql": { "type": "string", "description": "SQL query with ?-style positional placeholders." }, "params": { "type": "array", "items": { "type": "object" }, "description": "Positional parameter bindings for ? placeholders." } }, "required": ["sql"] }, "SqlStepErrorView": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." } }, "required": ["message"] }, "SqlStepResultView": { "type": "object", "properties": { "success": { "description": "Result on success.", "anyOf": [ { "$ref": "#/components/schemas/SqlQueryResultView" }, { "type": "null" } ] }, "error": { "description": "Error on failure.", "anyOf": [ { "$ref": "#/components/schemas/SqlStepErrorView" }, { "type": "null" } ] } } }, "StripeBillingInfo": { "type": "object", "description": "Stripe billing information.", "properties": { "customer_id": { "description": "The Stripe customer ID.", "type": ["string", "null"] }, "active_subscription": { "description": "The active Stripe subscription ID.", "type": ["string", "null"] } } }, "TunnelAuthMode": { "type": "string", "enum": ["open", "authenticated"] }, "TunnelAuthModeView": { "type": "string", "enum": ["open", "authenticated"] }, "TunnelConfig": { "type": "object", "description": "Configuration for creating a V2 tunnel. When specified at Devbox creation, a tunnel will be automatically provisioned.", "properties": { "auth_mode": { "description": "Authentication mode for the tunnel. Defaults to open if omitted: the hostname is a public capability and does not require a tunnel bearer token.", "anyOf": [ { "$ref": "#/components/schemas/TunnelAuthMode" }, { "type": "null" } ] }, "http_keep_alive": { "description": "When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. Defaults to true if not specified.", "type": ["boolean", "null"] }, "wake_on_http": { "description": "When true, HTTP traffic to a suspended devbox will automatically trigger a resume. Defaults to false if not specified. Prefer lifecycle.resume_triggers.http on launch_parameters for new integrations. If both are set, lifecycle.resume_triggers.http takes precedence.", "type": ["boolean", "null"] } } }, "TunnelView": { "type": "object", "description": "A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels allow external clients to reach web servers, APIs, or other HTTP services running inside a Devbox without requiring direct network access. Each tunnel is uniquely identified by an encrypted tunnel_key and can be configured for either open (public) or authenticated access.\nUsage: https://{port}-{tunnel_key}.tunnel.runloop.ai. Authenticated tunnels should pass auth_token as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.", "properties": { "tunnel_key": { "type": "string", "description": "The encrypted tunnel key used to construct the tunnel URL. URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}" }, "auth_mode": { "$ref": "#/components/schemas/TunnelAuthModeView", "description": "The authentication mode for the tunnel." }, "auth_token": { "description": "Bearer token for tunnel authentication. Only present when auth_mode is 'authenticated'. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.", "type": ["string", "null"] }, "create_time_ms": { "type": "integer", "format": "int64", "description": "Creation time of the tunnel (Unix timestamp milliseconds)." }, "http_keep_alive": { "type": "boolean", "description": "When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer." }, "wake_on_http": { "type": "boolean", "description": "When true, HTTP traffic to a suspended devbox will automatically trigger a resume." } }, "required": [ "tunnel_key", "auth_mode", "create_time_ms", "http_keep_alive", "wake_on_http" ] }, "UserParameters": { "type": "object", "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"] } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/pty/{session_name}": { "get": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Create or reconnect to a PTY session.", "description": "Looks up the PTY session identified by the path session_name and either reconnects to the existing session or creates it if it does not yet exist. The session_name is a client-chosen session identifier, not an opaque server-issued ID. It must be non-empty (1..=256 chars) and use only ASCII letters, digits, '-' and '_'. A newly created PTY session starts an interactive bash shell on the Devbox. Optional cols and rows query parameters apply an initial terminal size before any I/O; they must both be present and in the range 1..=1000 to take effect. The response returns a PtyConnectView containing connect_url (a server-relative path to the WebSocket data plane), idle_ttl_seconds (how long this session is retained after the last client disconnects), and the resulting cols/rows. The interactive terminal byte stream is exchanged over the WebSocket data plane and is not modeled in this OpenAPI contract; clients should connect to connect_url and exchange raw binary frames for terminal I/O. The single-attach contract is enforced when a client opens the WebSocket data plane, not on this bootstrap call: bootstrap always succeeds for a valid session_name, even if another client is currently attached. Rejection of a second concurrent attach happens at WebSocket upgrade time. If the active client disconnects, the session is preserved for the idle TTL so a later connect using the same session_name resumes the same shell. After the TTL expires, after an explicit close control action, or after the underlying Devbox lifecycle replaces the PTY process (such as through suspend/resume), a later request with the same session_name creates a fresh PTY session without the previous shell state.", "operationId": "connectDevboxPtySession", "parameters": [ { "name": "session_name", "in": "path", "description": "The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. Reusing the same name reconnects to the same logical PTY session when it is still available.", "required": true, "schema": { "type": "string" } }, { "name": "cols", "in": "query", "description": "Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored.", "schema": { "type": "integer", "format": "int32" } }, { "name": "rows", "in": "query", "description": "Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtyConnectView" } } } }, "400": { "description": "Malformed session_name (alphabet or length out of range)." }, "503": { "description": "PTY session could not be spawned (host resource exhaustion)." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ptyConnectView = await client.pty.connect('session_name');\n\nconsole.log(ptyConnectView.idle_ttl_seconds);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npty_connect_view = client.pty.connect(\n session_name=\"session_name\",\n)\nprint(pty_connect_view.idle_ttl_seconds)" } ] } }, "/pty/{session_name}/control": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Send a control command to a PTY session.", "description": "Applies a PTY control operation to an existing session. The action field selects the operation; the other fields in PtyControlParams are interpreted only when they are relevant to the chosen action.\n\nresize: cols and rows are required and must each be in 1..=1000. A 0 or out-of-range value returns 400. The new winsize is applied to the PTY master and the kernel delivers SIGWINCH to the foreground process group.\n\nsignal: signal is the POSIX signal name (for example 'SIGTERM', 'SIGHUP', 'SIGINT', 'SIGUSR1'). Unknown signal names return 400. The signal is delivered to the slave's foreground process group via killpg(2). If the shell has already exited and there is no foreground process group, returns 400.\n\nclose: terminates the session. Sends SIGHUP to the foreground process group (best-effort; ignored if the shell has already exited) and drops the session from the server's session cache. A subsequent connect with the same session_name will create a fresh PTY session.", "operationId": "controlDevboxPtySession", "parameters": [ { "name": "session_name", "in": "path", "description": "The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtyControlParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtyControlResultView" } } } }, "400": { "description": "Invalid action parameters: out-of-range cols/rows on resize, unknown signal name on signal, or no foreground process group on signal." }, "404": { "description": "PTY session not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ptyControlResultView = await client.pty.control('session_name');\n\nconsole.log(ptyControlResultView.session_name);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npty_control_result_view = client.pty.control(\n session_name=\"session_name\",\n)\nprint(pty_control_result_view.session_name)" } ] } }, "/v1/accounts/me": { "get": { "tags": ["accounts"], "summary": "Get the authenticated caller's account.", "description": "Returns the account the API key or session is authenticated against, including id, name, tier, and billing summary.", "operationId": "getCurrentAccount", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst accountView = await client.accounts.me();\n\nconsole.log(accountView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naccount_view = client.accounts.me()\nprint(account_view.id)" } ] } }, "/v1/agents": { "post": { "tags": ["agents"], "summary": "Create an Agent.", "description": "Create a new Agent with a name and optional public visibility. The Agent will be assigned a unique ID.", "operationId": "createAgent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateParameters" } } } }, "responses": { "200": { "description": "Agent created successfully. Returns the Agent with metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } }, "400": { "description": "Bad request. Invalid name or parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst agentView = await client.agents.create({ name: 'name' });\n\nconsole.log(agentView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nagent_view = client.agents.create(\n name=\"name\",\n)\nprint(agent_view.id)" } ] }, "get": { "tags": ["agents"], "summary": "List Agents.", "description": "List all Agents for the authenticated account with pagination support.", "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter agents by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "is_public", "in": "query", "description": "Filter agents by public visibility.", "allowEmptyValue": true, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search by agent ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Filter by version. Use 'latest' to get the most recently created agent.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of Agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const agentView of client.agents.list()) {\n console.log(agentView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.agents.list()\npage = page.agents[0]\nprint(page.id)" } ] } }, "/v1/agents/devbox_counts": { "get": { "tags": ["agents"], "summary": "Get Devbox counts by Agent.", "description": "Returns devbox counts grouped by agent name. This endpoint efficiently aggregates devbox counts for all agents in a single request, avoiding N+1 query patterns.", "operationId": "getAgentDevboxCounts", "responses": { "200": { "description": "Successfully retrieved devbox counts by agent name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDevboxCountsView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst agentDevboxCountsView = await client.agents.devboxCounts();\n\nconsole.log(agentDevboxCountsView.counts);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nagent_devbox_counts_view = client.agents.devbox_counts()\nprint(agent_devbox_counts_view.counts)" } ] } }, "/v1/agents/list_public": { "get": { "tags": ["agents"], "summary": "List Public Agents.", "description": "List all public Agents with pagination support.", "operationId": "listPublicAgents", "parameters": [ { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter agents by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by agent ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Filter by version. Use 'latest' to get the most recently created agent.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of public Agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const agentView of client.agents.listPublic()) {\n console.log(agentView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.agents.list_public()\npage = page.agents[0]\nprint(page.id)" } ] } }, "/v1/agents/{id}": { "get": { "tags": ["agents"], "summary": "Get an Agent.", "description": "Retrieve a specific Agent by its unique identifier.", "operationId": "getAgent", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Agent to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Agent not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst agentView = await client.agents.retrieve('id');\n\nconsole.log(agentView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nagent_view = client.agents.retrieve(\n \"id\",\n)\nprint(agent_view.id)" } ] } }, "/v1/agents/{id}/delete": { "post": { "tags": ["agents"], "summary": "Delete an Agent.", "description": "Delete an Agent by its unique identifier. The Agent will be permanently removed.", "operationId": "deleteAgent", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Agent to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Agent not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst agent = await client.agents.delete('id');\n\nconsole.log(agent);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nagent = client.agents.delete(\n \"id\",\n)\nprint(agent)" } ] } }, "/v1/apikeys": { "post": { "tags": ["apikeys"], "summary": "Create API Key.", "description": "Create a new API key for the authenticated account. Use a standard API key (ak_) or a restricted key (rk_) with RESOURCE_TYPE_ACCOUNT write scope.", "operationId": "createAPIKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKeyCreatedView = await client.apikeys.create();\n\nconsole.log(apiKeyCreatedView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\napi_key_created_view = client.apikeys.create()\nprint(api_key_created_view.id)" } ] } }, "/v1/axons": { "post": { "tags": ["axons"], "summary": "[Beta] Create an axon.", "description": "[Beta] Create a new axon.", "operationId": "createAxon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonCreateParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axonView = await client.axons.create();\n\nconsole.log(axonView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naxon_view = client.axons.create()\nprint(axon_view.id)" } ] }, "get": { "tags": ["axons"], "summary": "[Beta] List axons.", "description": "[Beta] List axons, including deleted axons. Deleted axons include their deletion time.", "operationId": "listActiveAxons", "parameters": [ { "name": "name", "in": "query", "description": "Filter by axon name (prefix match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by axon ID.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by axon ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key]", "in": "query", "description": "Filter axons by metadata key-value pair. Can be used multiple times for different keys.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key][in]", "in": "query", "description": "Filter axons by metadata key with multiple possible values (OR condition).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonListView" } } } }, "400": { "description": "Invalid resource ID filter." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const axonView of client.axons.list()) {\n console.log(axonView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.axons.list()\npage = page.axons[0]\nprint(page.id)" } ] } }, "/v1/axons/metadata/keys": { "get": { "tags": ["axons"], "summary": "[Beta] List available axon metadata keys.", "description": "[Beta] Returns a list of all available metadata keys that can be used for filtering axons.", "operationId": "getAxonMetadataKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/v1/axons/metadata/keys/{key}/values": { "get": { "tags": ["axons"], "summary": "[Beta] List values for a specific axon metadata key.", "description": "[Beta] Returns a list of all values that exist for a specific metadata key across all axons.", "operationId": "getAxonMetadataValues", "parameters": [ { "name": "key", "in": "path", "description": "The metadata key to get values for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/v1/axons/{id}": { "get": { "tags": ["axons"], "summary": "[Beta] Get an axon.", "description": "[Beta] Get an axon by ID. Deleted axons remain readable and include their deletion time.", "operationId": "getAxon", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonView" } } } }, "404": { "description": "Axon not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axonView = await client.axons.retrieve('id');\n\nconsole.log(axonView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naxon_view = client.axons.retrieve(\n \"id\",\n)\nprint(axon_view.id)" } ] }, "post": { "tags": ["axons"], "summary": "[Beta] Update an axon.", "description": "[Beta] Updates the specified axon fields. Omitted fields are left unchanged. An empty metadata map clears the metadata. Deleted axons remain readable but cannot be updated.", "operationId": "updateAxon", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonUpdateParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonView" } } } }, "404": { "description": "Axon not found." }, "409": { "description": "Axon has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axonView = await client.axons.update('id');\n\nconsole.log(axonView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naxon_view = client.axons.update(\n id=\"id\",\n)\nprint(axon_view.id)" } ] }, "delete": { "tags": ["axons"], "summary": "[Beta] Delete an axon.", "description": "[Beta] Delete an axon's event data. The axon's registry record remains readable.", "operationId": "deleteAxon", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "404": { "description": "Axon not found." }, "409": { "description": "Axon has already been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axon = await client.axons.delete('id');\n\nconsole.log(axon);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naxon = client.axons.delete(\n \"id\",\n)\nprint(axon)" } ] } }, "/v1/axons/{id}/events": { "get": { "tags": ["axons"], "summary": "[Beta] List events for an axon.", "description": "[Beta] List events from an axon's event stream, ordered by sequence descending.", "operationId": "listAxonEvents", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonEventListView" } } } }, "404": { "description": "Axon not found." }, "410": { "description": "Axon event data has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axonEventListView = await client.axons.events.list('id');\n\nconsole.log(axonEventListView.events);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\naxon_event_list_view = client.axons.events.list(\n id=\"id\",\n)\nprint(axon_event_list_view.events)" } ] } }, "/v1/axons/{id}/publish": { "post": { "tags": ["axons"], "summary": "[Beta] Publish an event to an axon.", "description": "[Beta] Publish an event to a specified axon.", "operationId": "publishToAxon", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResultView" } } } }, "404": { "description": "Axon not found." }, "409": { "description": "Axon has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst publishResultView = await client.axons.publish('id', {\n event_type: 'event_type',\n origin: 'EXTERNAL_EVENT',\n payload: 'payload',\n source: 'source',\n});\n\nconsole.log(publishResultView.sequence);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npublish_result_view = client.axons.publish(\n id=\"id\",\n event_type=\"event_type\",\n origin=\"EXTERNAL_EVENT\",\n payload=\"payload\",\n source=\"source\",\n)\nprint(publish_result_view.sequence)" } ] } }, "/v1/axons/{id}/sql/batch": { "post": { "tags": ["axons"], "summary": "[Beta] Execute a batch of SQL statements against an axon's database.", "description": "[Beta] Execute multiple SQL statements atomically within a single transaction against an axon's SQLite database.", "operationId": "axonSqlBatch", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlBatchParams" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlBatchResultView" } } } }, "404": { "description": "Axon not found." }, "410": { "description": "Axon database has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst sqlBatchResultView = await client.axons.sql.batch('id', { statements: [{ sql: 'sql' }] });\n\nconsole.log(sqlBatchResultView.results);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsql_batch_result_view = client.axons.sql.batch(\n id=\"id\",\n statements=[{\n \"sql\": \"sql\"\n }],\n)\nprint(sql_batch_result_view.results)" } ] } }, "/v1/axons/{id}/sql/query": { "post": { "tags": ["axons"], "summary": "[Beta] Execute a SQL query against an axon's database.", "description": "[Beta] Execute a single parameterized SQL statement against an axon's SQLite database.", "operationId": "axonSqlQuery", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlStatementParams" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlQueryResultView" } } } }, "404": { "description": "Axon not found." }, "410": { "description": "Axon database has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst sqlQueryResultView = await client.axons.sql.query('id', { sql: 'sql' });\n\nconsole.log(sqlQueryResultView.columns);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsql_query_result_view = client.axons.sql.query(\n id=\"id\",\n sql=\"sql\",\n)\nprint(sql_query_result_view.columns)" } ] } }, "/v1/axons/{id}/subscribe/sse": { "get": { "tags": ["axons"], "summary": "[Beta] Subscribe to an axon event stream via SSE.", "description": "[Beta] Subscribe to an axon event stream via server-sent events.", "operationId": "subscribeToAxonSse", "parameters": [ { "name": "id", "in": "path", "description": "The axon identifier.", "required": true, "schema": { "type": "string" } }, { "name": "after_sequence", "in": "query", "description": "Sequence number after which to start streaming. Events with sequence > this value are returned. If unset, replay from the beginning.", "allowEmptyValue": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonEventView" } } }, "headers": { "Content-Type": { "description": "text/event-stream", "schema": { "type": "string" } } } }, "404": { "description": "Axon not found." }, "410": { "description": "Axon event data has been deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst axonEventView = await client.axons.subscribeSse('id');\n\nconsole.log(axonEventView.axon_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nfor axon in client.axons.subscribe_sse(\n id=\"id\",\n):\n print(axon)" } ] } }, "/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", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintBuildParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst blueprintView = await client.blueprints.create({ name: 'name' });\n\nconsole.log(blueprintView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nblueprint_view = client.blueprints.create(\n name=\"name\",\n)\nprint(blueprint_view.id)" } ] }, "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", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by build status (queued, provisioning, building, failed, build_complete)", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintListView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const blueprintView of client.blueprints.list()) {\n console.log(blueprintView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.blueprints.list()\npage = page.blueprints[0]\nprint(page.id)" } ] } }, "/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", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by build status (queued, provisioning, building, failed, build_complete)", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintListView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const blueprintView of client.blueprints.listPublic()) {\n console.log(blueprintView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.blueprints.list_public()\npage = page.blueprints[0]\nprint(page.id)" } ] } }, "/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", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/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, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/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", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintBuildParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreviewView" } } } } }, "deprecated": true, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst blueprintPreviewView = await client.blueprints.preview({ name: 'name' });\n\nconsole.log(blueprintPreviewView.dockerfile);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nblueprint_preview_view = client.blueprints.preview(\n name=\"name\",\n)\nprint(blueprint_preview_view.dockerfile)" } ] } }, "/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", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/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, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/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, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst blueprintView = await client.blueprints.retrieve('id');\n\nconsole.log(blueprintView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nblueprint_view = client.blueprints.retrieve(\n \"id\",\n)\nprint(blueprint_view.id)" } ] } }, "/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, "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." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst blueprint = await client.blueprints.delete('id');\n\nconsole.log(blueprint);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nblueprint = client.blueprints.delete(\n \"id\",\n)\nprint(blueprint)" } ] } }, "/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, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintBuildLogsListView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst blueprintBuildLogsListView = await client.blueprints.logs('id');\n\nconsole.log(blueprintBuildLogsListView.blueprint_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nblueprint_build_logs_list_view = client.blueprints.logs(\n \"id\",\n)\nprint(blueprint_build_logs_list_view.blueprint_id)" } ] } }, "/v1/devboxes": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Create a Devbox.", "description": "Create a Devbox and begin the boot process. Standard Devboxes initially report the 'provisioning' state. FLEX Devboxes initially report the 'queued' state while waiting for infrastructure allocation, then transition to 'provisioning' once assigned to a node. The Devbox transitions to 'initializing' while the booted Devbox runs Runloop or user-defined setup scripts, then to 'running' when it is ready for use.", "operationId": "createDevbox", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxCreateParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.create();\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.create()\nprint(devbox_view.id)" } ] }, "get": { "tags": ["Devbox"], "summary": "List Devboxes.", "description": "List all Devboxes while optionally filtering by status.", "operationId": "listDevboxes", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "allowEmptyValue": true, "schema": { "$ref": "#/components/schemas/DevboxViewStatus" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxListView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const devboxView of client.devboxes.list()) {\n console.log(devboxView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.devboxes.list()\npage = page.devboxes[0]\nprint(page.id)" } ] } }, "/v1/devboxes/disk_snapshots": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List disk snapshots of a Devbox.", "description": "List all snapshots of a Devbox while optionally filtering by Devbox ID, source Blueprint ID, and metadata.", "operationId": "getDevboxDiskSnapshotList", "parameters": [ { "name": "devbox_id", "in": "query", "description": "Devbox ID to filter by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "source_blueprint_id", "in": "query", "description": "Source Blueprint ID to filter snapshots by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key]", "in": "query", "description": "Filter snapshots by metadata key-value pair. Can be used multiple times for different keys.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key][in]", "in": "query", "description": "Filter snapshots by metadata key with multiple possible values (OR condition).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDiskSnapshotListView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const devboxSnapshotView of client.devboxes.listDiskSnapshots()) {\n console.log(devboxSnapshotView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.devboxes.list_disk_snapshots()\npage = page.snapshots[0]\nprint(page.id)" } ] } }, "/v1/devboxes/disk_snapshots/list_public": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List public disk snapshots.", "description": "List all public disk snapshots that are available to all users.", "operationId": "listPublicSnapshots", "parameters": [ { "name": "devbox_id", "in": "query", "description": "Devbox ID to filter by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "source_blueprint_id", "in": "query", "description": "Source Blueprint ID to filter snapshots by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key]", "in": "query", "description": "Filter snapshots by metadata key-value pair. Can be used multiple times for different keys.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "metadata[key][in]", "in": "query", "description": "Filter snapshots by metadata key with multiple possible values (OR condition).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDiskSnapshotListView" } } } } } } }, "/v1/devboxes/disk_snapshots/metadata/keys": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List available snapshot metadata keys.", "description": "Returns a list of all available metadata keys that can be used for filtering snapshots.", "operationId": "getSnapshotMetadataKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/v1/devboxes/disk_snapshots/metadata/keys/{key}/values": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List values for a specific snapshot metadata key.", "description": "Returns a list of all values that exist for a specific metadata key across all snapshots.", "operationId": "getSnapshotMetadataValues", "parameters": [ { "name": "key", "in": "path", "description": "The metadata key to get values for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/v1/devboxes/disk_snapshots/public/metadata/keys": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List available public snapshot metadata keys.", "description": "Returns a list of all available metadata keys from public snapshots only that can be used for filtering.", "operationId": "getPublicSnapshotMetadataKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/v1/devboxes/disk_snapshots/public/metadata/keys/{key}/values": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "List values for a specific public snapshot metadata key.", "description": "Returns a list of all values that exist for a specific metadata key across all public snapshots only.", "operationId": "getPublicSnapshotMetadataValues", "parameters": [ { "name": "key", "in": "path", "description": "The metadata key to get values for from public snapshots.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/v1/devboxes/disk_snapshots/{id}": { "post": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "Update metadata of Disk Snapshot.", "description": "Updates disk snapshot metadata via update vs patch. The entire metadata will be replaced.", "operationId": "updateDiskSnapshot", "parameters": [ { "name": "id", "in": "path", "description": "The Snapshot ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSnapshotRequest" } } } }, "responses": { "200": { "description": "Snapshot created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDiskSnapshotView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxSnapshotView = await client.devboxes.diskSnapshots.update('id');\n\nconsole.log(devboxSnapshotView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_snapshot_view = client.devboxes.disk_snapshots.update(\n id=\"id\",\n)\nprint(devbox_snapshot_view.id)" } ] } }, "/v1/devboxes/disk_snapshots/{id}/delete": { "post": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "Delete a disk snapshot of a Devbox.", "description": "Delete a previously taken disk snapshot of a Devbox.", "operationId": "deleteSnapshot", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the snapshot.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshot deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "404": { "description": "Snapshot not found." }, "409": { "description": "Only successfully created snapshots can be deleted." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.deleteDiskSnapshot('id');\n\nconsole.log(response);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.delete_disk_snapshot(\n \"id\",\n)\nprint(response)" } ] } }, "/v1/devboxes/disk_snapshots/{id}/status": { "get": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "Query the status of an asynchronous disk snapshot.", "description": "Get the current status of an asynchronous disk snapshot operation, including whether it is still in progress and any error messages if it failed.", "operationId": "queryDiskSnapshotAsync", "parameters": [ { "name": "id", "in": "path", "description": "The Snapshot ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshot status retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSnapshotAsyncStatusView" } } } }, "404": { "description": "Snapshot not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxSnapshotAsyncStatusView = await client.devboxes.diskSnapshots.queryStatus('id');\n\nconsole.log(devboxSnapshotAsyncStatusView.status);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_snapshot_async_status_view = client.devboxes.disk_snapshots.query_status(\n \"id\",\n)\nprint(devbox_snapshot_async_status_view.status)" } ] } }, "/v1/devboxes/evictions/watch": { "get": { "summary": "Stream infrastructure eviction warnings for the account via SSE.", "description": "Subscribe, via server-sent events, to pending infrastructure evictions for every Devbox in the account. On connect the stream emits one event per Devbox that currently has a pending eviction, then one event as each further eviction is scheduled. Best-effort and advisory: a Devbox stays running until its deadline, and delivery is not guaranteed.", "operationId": "watchDevboxEvictions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxEvictionEventView" } } }, "headers": { "Content-Type": { "description": "text/event-stream", "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxEvictionEventView = await client.devboxes.watchEvictions();\n\nconsole.log(devboxEvictionEventView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nfor devbox in client.devboxes.watch_evictions():\n print(devbox)" } ] } }, "/v1/devboxes/metadata/keys": { "get": { "tags": ["Devbox"], "summary": "List available devbox metadata keys.", "description": "Returns a list of all available metadata keys that can be used for filtering devboxes.", "operationId": "getDevboxMetadataKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/v1/devboxes/metadata/keys/{key}/values": { "get": { "tags": ["Devbox"], "summary": "List values for a specific devbox metadata key.", "description": "Returns a list of all values that exist for a specific metadata key across all devboxes.", "operationId": "getDevboxMetadataValues", "parameters": [ { "name": "key", "in": "path", "description": "The metadata key to get values for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}": { "get": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Get status of an asynchronous execution on a Devbox.", "description": "Get the latest status of a previously launched asynchronous execuction including stdout/error and the exit code if complete.", "operationId": "queryAsyncCommand", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The Devbox ID", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The Execution ID", "required": true, "schema": { "type": "string" } }, { "name": "last_n", "in": "query", "description": "Last n lines of standard error / standard out to return (default: 100)", "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxAsyncExecutionDetailView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxAsyncExecutionDetailView = await client.devboxes.executions.retrieve(\n 'devbox_id',\n 'execution_id',\n);\n\nconsole.log(devboxAsyncExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_async_execution_detail_view = client.devboxes.executions.retrieve(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n)\nprint(devbox_async_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}/kill": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Kill an asynchronous execution currently running on a devbox", "description": "Kill a previously launched asynchronous execution if it is still running by killing the launched process. Optionally kill the entire process group.", "operationId": "killAsyncExecution", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The Async Execution ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxKillExecutionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxAsyncExecutionDetailView" } } } }, "404": { "description": "Devbox or Execution not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxAsyncExecutionDetailView = await client.devboxes.executions.kill(\n 'devbox_id',\n 'execution_id',\n);\n\nconsole.log(devboxAsyncExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_async_execution_detail_view = client.devboxes.executions.kill(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n)\nprint(devbox_async_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}/send_std_in": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Send Content to Std In for a running execution.", "description": "Send nonempty text or a signal to an execution started with attach_stdin enabled. The request body is required. Supply exactly one of nonempty text or a non-null signal. Wait for each send before sending more input or EOF; concurrent requests are not ordered and retries after connection failures can replay input.", "operationId": "sendStdIn", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The Async Execution ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSendStdInRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSendStdInResult" } } } }, "404": { "description": "Devbox or Execution not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxSendStdInResult = await client.devboxes.executions.sendStdIn(\n 'devbox_id',\n 'execution_id',\n);\n\nconsole.log(devboxSendStdInResult.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_send_std_in_result = client.devboxes.executions.send_std_in(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n)\nprint(devbox_send_std_in_result.devbox_id)" } ] } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}/stream_stderr_updates": { "get": { "tags": ["executions", "streaming"], "summary": "Tails the stderr logs for the given execution with SSE streaming", "description": "Tails the stderr logs for the given execution with SSE streaming", "operationId": "streamStdErrUpdates", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The ID of the devbox.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The ID of the execution.", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "The byte offset to start the stream from (if unspecified, starts from the beginning of the stream)", "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecUpdateChunkView" } } }, "headers": { "Content-Type": { "description": "text/event-stream", "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst executionUpdateChunk = await client.devboxes.executions.streamStderrUpdates(\n 'devbox_id',\n 'execution_id',\n);\n\nconsole.log(executionUpdateChunk.output);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nfor execution in client.devboxes.executions.stream_stderr_updates(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n):\n print(execution)" } ] } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}/stream_stdout_updates": { "get": { "tags": ["executions", "streaming"], "summary": "Tails the stdout logs for the given execution with SSE streaming", "description": "Tails the stdout logs for the given execution with SSE streaming", "operationId": "streamStdOutUpdates", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The ID of the devbox.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The ID of the execution.", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "The byte offset to start the stream from (if unspecified, starts from the beginning of the stream)", "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecUpdateChunkView" } } }, "headers": { "Content-Type": { "description": "text/event-stream", "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst executionUpdateChunk = await client.devboxes.executions.streamStdoutUpdates(\n 'devbox_id',\n 'execution_id',\n);\n\nconsole.log(executionUpdateChunk.output);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nfor execution in client.devboxes.executions.stream_stdout_updates(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n):\n print(execution)" } ] } }, "/v1/devboxes/{devbox_id}/executions/{execution_id}/wait_for_status": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Wait for an asynchronous execution to reach a specific status.", "description": "Polls the asynchronous execution's status until it reaches one of the desired statuses or times out. Max is 25 seconds.", "operationId": "waitForCommandCompletion", "parameters": [ { "name": "devbox_id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "description": "The Async Execution ID.", "required": true, "schema": { "type": "string" } }, { "name": "last_n", "in": "query", "description": "Last n lines of standard error / standard out to return (default: 100)", "allowEmptyValue": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxWaitForCommandRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxAsyncExecutionDetailView" } } } }, "400": { "description": "Invalid status provided or Devbox not in proper state." }, "404": { "description": "Devbox or Execution not found." }, "408": { "description": "Timeout waiting for command completion." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxAsyncExecutionDetailView = await client.devboxes.waitForCommand(\n 'devbox_id',\n 'execution_id',\n { statuses: ['queued'] },\n);\n\nconsole.log(devboxAsyncExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_async_execution_detail_view = client.devboxes.wait_for_command(\n execution_id=\"execution_id\",\n devbox_id=\"devbox_id\",\n statuses=[\"queued\"],\n)\nprint(devbox_async_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{id}": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Update a Devbox.", "description": "Updates the specified Devbox fields. Omitted fields are left unchanged. An empty name clears the name, and an empty metadata map clears the metadata.", "operationId": "updateDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxUpdateParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.update('id');\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.update(\n id=\"id\",\n)\nprint(devbox_view.id)" } ] }, "get": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Get Devbox details.", "description": "Get the latest details and status of a Devbox.", "operationId": "getDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.retrieve('id');\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.retrieve(\n \"id\",\n)\nprint(devbox_view.id)" } ] } }, "/v1/devboxes/{id}/create_gateway_token": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "Mint an agent gateway token for a Devbox.", "description": "Mint a token that lets a running Devbox call an external API through the Runloop agent gateway, using the credential in the supplied secret. The gateway applies the credential to proxied requests, so the real API key is never exposed to the Devbox.\n\nThe token is bound to this Devbox and is only accepted for requests that originate from it. Nothing is stored on the Devbox: the token is returned to the caller and is not re-issued when the Devbox is resumed.", "operationId": "createDevboxGatewayToken", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTokenCreateParameters" } } } }, "responses": { "200": { "description": "Gateway token minted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTokenView" } } } }, "400": { "description": "Devbox is not currently running, or the gateway config or secret was not found." }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst gatewayTokenView = await client.devboxes.createGatewayToken('id', {\n gateway: 'gateway',\n secret: 'secret',\n});\n\nconsole.log(gatewayTokenView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ngateway_token_view = client.devboxes.create_gateway_token(\n id=\"id\",\n gateway=\"gateway\",\n secret=\"secret\",\n)\nprint(gateway_token_view.devbox_id)" } ] } }, "/v1/devboxes/{id}/create_mcp_token": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "[Beta] Mint an MCP token for a Devbox.", "description": "[Beta] Mint a token that lets a running Devbox reach an upstream MCP (Model Context Protocol) server through the Runloop MCP hub, using the credential in the supplied secret. Tool access is limited to the MCP config's allowed_tools, and the credential itself is never exposed to the Devbox.\n\nThe token is bound to this Devbox and is only accepted for requests that originate from it. Nothing is stored on the Devbox: the token is returned to the caller and is not re-issued when the Devbox is resumed.", "operationId": "createDevboxMcpToken", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpTokenCreateParameters" } } } }, "responses": { "200": { "description": "MCP token minted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpTokenView" } } } }, "400": { "description": "Devbox is not currently running, or the MCP config or secret was not found." }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mcpTokenView = await client.devboxes.createMcpToken('id', {\n mcp_config: 'mcp_config',\n secret: 'secret',\n});\n\nconsole.log(mcpTokenView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nmcp_token_view = client.devboxes.create_mcp_token(\n id=\"id\",\n mcp_config=\"mcp_config\",\n secret=\"secret\",\n)\nprint(mcp_token_view.devbox_id)" } ] } }, "/v1/devboxes/{id}/create_pty_tunnel": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "Create an ephemeral PTY tunnel for a running Devbox.", "description": "Create an ephemeral authenticated tunnel for terminal access to a running Devbox. This tunnel is not persisted on the Devbox and is generated fresh on each request. The returned auth_token should be passed as a Bearer token in the X-Runloop-Tunnel-Authorization header.", "operationId": "createDevboxPtyTunnel", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtyTunnelView" } } } }, "400": { "description": "Devbox is not currently running." }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ptyTunnelView = await client.devboxes.createPtyTunnel('id');\n\nconsole.log(ptyTunnelView.auth_token);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npty_tunnel_view = client.devboxes.create_pty_tunnel(\n \"id\",\n)\nprint(pty_tunnel_view.auth_token)" } ] } }, "/v1/devboxes/{id}/create_ssh_key": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "Create an SSH key for a Devbox", "description": "Create an SSH key for a Devbox to enable remote access.", "operationId": "createDevboxSshKey", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxCreateSshKeyView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.createSSHKey('id');\n\nconsole.log(response.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.create_ssh_key(\n \"id\",\n)\nprint(response.id)" } ] } }, "/v1/devboxes/{id}/download_file": { "post": { "tags": ["Devbox", "Devbox-FileTools"], "summary": "Download binary file contents from Devbox filesystem.", "description": "Download file contents of any type (binary, text, etc) from a specified path on the Devbox.", "operationId": "devboxDownloadFile", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDownloadFileParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/octet-stream": { "schema": { "format": "binary" } } }, "headers": { "Content-Type": { "description": "application/octet-stream", "required": true, "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment", "required": true, "schema": { "type": "string" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.downloadFile('id', { path: 'path' });\n\nconsole.log(response);\n\nconst content = await response.blob();\nconsole.log(content);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.download_file(\n id=\"id\",\n path=\"path\",\n)\nprint(response)\ncontent = response.read()\nprint(content)" } ] } }, "/v1/devboxes/{id}/enable_tunnel": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "Enable a tunnel for a running Devbox.", "description": "Enable a V2 tunnel for an existing running Devbox. Tunnels provide encrypted URL-based access to the Devbox without exposing internal IDs. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai\n\nEach Devbox can have one tunnel. If tunnel config is omitted, or auth_mode is omitted, the tunnel defaults to open (public hostname, no bearer token).", "operationId": "enableDevboxTunnel", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TunnelConfig" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TunnelView" } } } }, "400": { "description": "Devbox is not running or already has a tunnel configured." }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst tunnelView = await client.devboxes.enableTunnel('id');\n\nconsole.log(tunnelView.auth_mode);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ntunnel_view = client.devboxes.enable_tunnel(\n id=\"id\",\n)\nprint(tunnel_view.auth_mode)" } ] } }, "/v1/devboxes/{id}/execute": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Execute a command with a known ID, optimistically waiting for completion", "description": "Execute a command with a known command ID on a devbox, optimistically waiting for it to complete within the specified timeout. If it completes in time, return the result. If not, return a status indicating the command is still running. Note: attach_stdin parameter is not supported; use execute_async for stdin support.", "operationId": "executeCommand", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "last_n", "in": "query", "description": "Last n lines of standard error / standard out to return (default: 100)", "allowEmptyValue": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxStartExecutionParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxAsyncExecutionDetailView" } } } }, "404": { "description": "Devbox not found." }, "408": { "description": "Command timed out." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxAsyncExecutionDetailView = await client.devboxes.execute('id', {\n command: 'command',\n command_id: 'command_id',\n});\n\nconsole.log(devboxAsyncExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_async_execution_detail_view = client.devboxes.execute(\n id=\"id\",\n command=\"command\",\n command_id=\"command_id\",\n)\nprint(devbox_async_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{id}/execute_async": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "Asynchronously execute a command via the Devbox shell", "description": "Execute the given command in the Devbox shell asynchronously and returns the execution that can be used to track the command's progress.", "operationId": "execAsyncCommand", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxCreateExecutionParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxAsyncExecutionDetailView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxAsyncExecutionDetailView = await client.devboxes.executeAsync('id', {\n command: 'command',\n});\n\nconsole.log(devboxAsyncExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_async_execution_detail_view = client.devboxes.execute_async(\n id=\"id\",\n command=\"command\",\n)\nprint(devbox_async_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{id}/execute_sync": { "post": { "tags": ["Devbox", "Devbox-ShellTools"], "summary": "(Deprecated, please use /execute_async) Synchronously execute a shell command on a Devbox", "description": "Execute a bash command in the Devbox shell, await the command completion and return the output. Note: attach_stdin parameter is not supported for synchronous execution.", "operationId": "execSyncCommand", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxCreateExecutionParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxExecutionDetailView" } } } } }, "deprecated": true, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxExecutionDetailView = await client.devboxes.executeSync('id', { command: 'command' });\n\nconsole.log(devboxExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_execution_detail_view = client.devboxes.execute_sync(\n id=\"id\",\n command=\"command\",\n)\nprint(devbox_execution_detail_view.devbox_id)" } ] } }, "/v1/devboxes/{id}/keep_alive": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Reset the idle timer of a running Devbox.", "description": "Send a 'Keep Alive' signal to a running Devbox that is configured to shutdown on idle so the idle time resets.", "operationId": "keepAliveDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.keepAlive('id');\n\nconsole.log(response);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.keep_alive(\n \"id\",\n)\nprint(response)" } ] } }, "/v1/devboxes/{id}/logs": { "get": { "tags": ["Devbox", "Devbox-ObservabilityTools"], "summary": "Get Devbox logs.", "description": "Get all logs from a running or completed Devbox.", "operationId": "listDevboxLogs", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "query", "description": "ID of execution to filter logs by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "shell_name", "in": "query", "description": "Shell Name to filter logs by.", "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxLogsListView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxLogsListView = await client.devboxes.logs.list('id');\n\nconsole.log(devboxLogsListView.logs);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_logs_list_view = client.devboxes.logs.list(\n id=\"id\",\n)\nprint(devbox_logs_list_view.logs)" } ] } }, "/v1/devboxes/{id}/logs/tail": { "get": { "tags": ["Devbox", "Devbox-ObservabilityTools"], "summary": "Live Tail Devbox Logs.", "description": "Tail the logs for the given devbox. This will return past log entries and continue streaming from there. The stream will then continue to stream logs until the connection is closed.", "operationId": "tailDevboxLogs", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "query", "description": "ID of execution to filter logs by.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "shell_name", "in": "query", "description": "Shell Name to filter logs by.", "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "description": "text/event-stream", "schema": { "type": "string" } } } }, "404": { "description": "Devbox not found." } } } }, "/v1/devboxes/{id}/read_file_contents": { "post": { "tags": ["Devbox", "Devbox-FileTools"], "summary": "Read text file contents from Devbox filesystem.", "description": "Read file contents from a file on a Devbox as a UTF-8. Note 'downloadFile' should be used for large files (greater than 100MB). Returns the file contents as a UTF-8 string.", "operationId": "devboxReadFileContents", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxReadFileParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.readFileContents('id', { file_path: 'file_path' });\n\nconsole.log(response);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.read_file_contents(\n id=\"id\",\n file_path=\"file_path\",\n)\nprint(response)" } ] } }, "/v1/devboxes/{id}/remove_tunnel": { "post": { "tags": ["Devbox", "Devbox-NetworkTools"], "summary": "Remove a tunnel from the Devbox.", "description": "Remove an existing V2 tunnel from the Devbox.", "operationId": "removeDevboxTunnel", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.removeTunnel('id');\n\nconsole.log(response);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.remove_tunnel(\n \"id\",\n)\nprint(response)" } ] } }, "/v1/devboxes/{id}/resume": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Resume a suspended Devbox", "description": "Resume a suspended Devbox with the disk state captured as suspend time. Note that any previously running processes or daemons will need to be restarted using the Devbox shell tools.", "operationId": "resumeDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } }, "400": { "description": "Devbox is not suspended." }, "404": { "description": "Devbox not found." }, "409": { "description": "A stored Devbox dependency required for resume is unavailable." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.resume('id');\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.resume(\n \"id\",\n)\nprint(devbox_view.id)" } ] } }, "/v1/devboxes/{id}/shutdown": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Shutdown a running Devbox.", "description": "Shutdown a running Devbox. This will permanently stop the Devbox. If you want to save the state of the Devbox, you should take a snapshot before shutting down or should suspend the Devbox instead of shutting down. If the Devbox has any in-progress snapshots, the shutdown will be rejected with a 409 Conflict unless force=true is specified.", "operationId": "shutdownDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "If true, force shutdown even if snapshots are in progress. Defaults to false.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } }, "409": { "description": "Devbox has in-progress snapshots and cannot be shut down at this time. Use force=true to override." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.shutdown('id');\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.shutdown(\n id=\"id\",\n)\nprint(devbox_view.id)" } ] } }, "/v1/devboxes/{id}/snapshot_disk": { "post": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "Synchronously create a disk snapshot of a running Devbox.", "description": "Create a disk snapshot of a devbox with the specified name and metadata to enable launching future Devboxes with the same disk state.", "operationId": "createDiskSnapshot", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSnapshotRequest" } } } }, "responses": { "200": { "description": "Snapshot created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDiskSnapshotView" } } } }, "404": { "description": "Devbox not found." }, "409": { "description": "The Devbox already has a snapshot in progress." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxSnapshotView = await client.devboxes.snapshotDisk('id');\n\nconsole.log(devboxSnapshotView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_snapshot_view = client.devboxes.snapshot_disk(\n id=\"id\",\n)\nprint(devbox_snapshot_view.id)" } ] } }, "/v1/devboxes/{id}/snapshot_disk_async": { "post": { "tags": ["Devbox", "Devbox-PersistenceTools"], "summary": "Start an asynchronous disk snapshot of a running Devbox.", "description": "Start an asynchronous disk snapshot of a devbox with the specified name and metadata. The snapshot operation will continue in the background and can be monitored using the query endpoint.", "operationId": "createDiskSnapshotAsync", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxSnapshotRequest" } } } }, "responses": { "200": { "description": "Snapshot operation started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxDiskSnapshotView" } } } }, "404": { "description": "Devbox not found." }, "409": { "description": "The Devbox already has a snapshot in progress." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxSnapshotView = await client.devboxes.snapshotDiskAsync('id');\n\nconsole.log(devboxSnapshotView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_snapshot_view = client.devboxes.snapshot_disk_async(\n id=\"id\",\n)\nprint(devbox_snapshot_view.id)" } ] } }, "/v1/devboxes/{id}/suspend": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Suspend a running Devbox", "description": "Suspend a running Devbox and create a disk snapshot to enable resuming the Devbox later with the same disk. Note this will not snapshot memory state such as running processes.", "operationId": "suspendDevbox", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } }, "400": { "description": "Devbox is not running." }, "404": { "description": "Devbox not found." }, "408": { "description": "Timed out waiting for the Devbox to suspend." }, "409": { "description": "Devbox failed or was shut down before the suspend completed." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxView = await client.devboxes.suspend('id');\n\nconsole.log(devboxView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_view = client.devboxes.suspend(\n \"id\",\n)\nprint(devbox_view.id)" } ] } }, "/v1/devboxes/{id}/upload_file": { "post": { "tags": ["Devbox", "Devbox-FileTools"], "summary": "Upload binary file contents to Devbox filesystem.", "description": "Upload file contents of any type (binary, text, etc) to a Devbox. Note this API is suitable for large files (larger than 100MB) and efficiently uploads files via multipart form data.", "operationId": "devboxUploadFile", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FileUpload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import fs from 'fs';\nimport Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.devboxes.uploadFile('id', { path: 'path' });\n\nconsole.log(response);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.devboxes.upload_file(\n id=\"id\",\n path=\"path\",\n)\nprint(response)" } ] } }, "/v1/devboxes/{id}/usage": { "get": { "tags": ["Devbox", "Devbox-ObservabilityTools"], "summary": "Get resource usage for a Devbox.", "description": "Get resource usage metrics for a specific Devbox. Returns CPU, memory, and disk consumption calculated from the Devbox's lifecycle, excluding any suspended periods for CPU and memory. Disk usage includes the full elapsed time since storage is consumed even when suspended.", "operationId": "getDevboxResourceUsage", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxResourceUsageView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxResourceUsageView = await client.devboxes.retrieveResourceUsage('id');\n\nconsole.log(devboxResourceUsageView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_resource_usage_view = client.devboxes.retrieve_resource_usage(\n \"id\",\n)\nprint(devbox_resource_usage_view.id)" } ] } }, "/v1/devboxes/{id}/wait_for_status": { "post": { "tags": ["Devbox", "Devbox-Lifecycle"], "summary": "Wait for a Devbox to reach one of the specified statuses.", "description": "Polls the Devbox's status until it reaches one of the desired statuses or times out.", "operationId": "waitForDevboxStatus", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxWaitForStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxView" } } } }, "400": { "description": "Invalid status provided." }, "404": { "description": "Devbox not found." }, "408": { "description": "Timeout waiting for status." } } } }, "/v1/devboxes/{id}/write_file_contents": { "post": { "tags": ["Devbox", "Devbox-FileTools"], "summary": "Write text file contents to Devbox filesystem.", "description": "Write UTF-8 string contents to a file at path on the Devbox. Note for large files (larger than 100MB), the upload_file endpoint must be used.", "operationId": "devboxWriteFileContents", "parameters": [ { "name": "id", "in": "path", "description": "The Devbox ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxWriteFileParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevboxExecutionDetailView" } } } }, "404": { "description": "Devbox not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst devboxExecutionDetailView = await client.devboxes.writeFileContents('id', {\n contents: 'contents',\n file_path: 'file_path',\n});\n\nconsole.log(devboxExecutionDetailView.devbox_id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ndevbox_execution_detail_view = client.devboxes.write_file_contents(\n id=\"id\",\n contents=\"contents\",\n file_path=\"file_path\",\n)\nprint(devbox_execution_detail_view.devbox_id)" } ] } }, "/v1/gateway-configs": { "post": { "tags": ["gateway-configs"], "summary": "Create a GatewayConfig.", "description": "Create a new GatewayConfig to proxy API requests through the agent gateway. The config specifies the target endpoint and how credentials should be applied.", "operationId": "createGatewayConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigCreateParameters" } } } }, "responses": { "200": { "description": "GatewayConfig created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigView" } } } }, "400": { "description": "Bad request. Name, endpoint, or auth mechanism is invalid." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst gatewayConfigView = await client.gatewayConfigs.create({\n auth_mechanism: { type: 'type' },\n endpoint: 'endpoint',\n name: 'name',\n});\n\nconsole.log(gatewayConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ngateway_config_view = client.gateway_configs.create(\n auth_mechanism={\n \"type\": \"type\"\n },\n endpoint=\"endpoint\",\n name=\"name\",\n)\nprint(gateway_config_view.id)" } ] }, "get": { "tags": ["gateway-configs"], "summary": "List GatewayConfigs.", "description": "List all GatewayConfigs for the authenticated account, including system-provided configs like 'anthropic' and 'openai'.", "operationId": "listGatewayConfigs", "parameters": [ { "name": "name", "in": "query", "description": "Filter by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by ID.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by gateway config ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of GatewayConfigs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigListView" } } } }, "400": { "description": "Invalid resource ID filter." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const gatewayConfigView of client.gatewayConfigs.list()) {\n console.log(gatewayConfigView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.gateway_configs.list()\npage = page.gateway_configs[0]\nprint(page.id)" } ] } }, "/v1/gateway-configs/{id}": { "get": { "tags": ["gateway-configs"], "summary": "Get a GatewayConfig.", "description": "Get a specific GatewayConfig by its unique identifier.", "operationId": "getGatewayConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the GatewayConfig.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the GatewayConfig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "GatewayConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst gatewayConfigView = await client.gatewayConfigs.retrieve('id');\n\nconsole.log(gatewayConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ngateway_config_view = client.gateway_configs.retrieve(\n \"id\",\n)\nprint(gateway_config_view.id)" } ] }, "post": { "tags": ["gateway-configs"], "summary": "Update a GatewayConfig.", "description": "Update an existing GatewayConfig. All fields are optional.", "operationId": "updateGatewayConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the GatewayConfig to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigUpdateParameters" } } } }, "responses": { "200": { "description": "GatewayConfig updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigView" } } } }, "400": { "description": "Bad request. Invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "GatewayConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst gatewayConfigView = await client.gatewayConfigs.update('id');\n\nconsole.log(gatewayConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ngateway_config_view = client.gateway_configs.update(\n id=\"id\",\n)\nprint(gateway_config_view.id)" } ] } }, "/v1/gateway-configs/{id}/delete": { "post": { "tags": ["gateway-configs"], "summary": "Delete a GatewayConfig.", "description": "Delete an existing GatewayConfig. This action is irreversible.", "operationId": "deleteGatewayConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the GatewayConfig to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "GatewayConfig deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayConfigView" } } } }, "400": { "description": "Bad request. Config is in use by active devboxes." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "GatewayConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst gatewayConfigView = await client.gatewayConfigs.delete('id');\n\nconsole.log(gatewayConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\ngateway_config_view = client.gateway_configs.delete(\n \"id\",\n)\nprint(gateway_config_view.id)" } ] } }, "/v1/mcp-configs": { "post": { "tags": ["mcp-configs"], "summary": "[Beta] Create an McpConfig.", "description": "[Beta] Create a new McpConfig to connect to an upstream MCP (Model Context Protocol) server. The config specifies the target endpoint and which tools are allowed.", "operationId": "createMcpConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigCreateParameters" } } } }, "responses": { "200": { "description": "McpConfig created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigView" } } } }, "400": { "description": "Bad request. Name, endpoint, or auth mechanism is invalid." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mcpConfigView = await client.mcpConfigs.create({\n allowed_tools: ['string'],\n endpoint: 'endpoint',\n name: 'name',\n});\n\nconsole.log(mcpConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nmcp_config_view = client.mcp_configs.create(\n allowed_tools=[\"string\"],\n endpoint=\"endpoint\",\n name=\"name\",\n)\nprint(mcp_config_view.id)" } ] }, "get": { "tags": ["mcp-configs"], "summary": "[Beta] List McpConfigs.", "description": "[Beta] List all McpConfigs for the authenticated account.", "operationId": "listMcpConfigs", "parameters": [ { "name": "name", "in": "query", "description": "Filter by name (prefix match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by ID.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by MCP config ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of McpConfigs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigListView" } } } }, "400": { "description": "Invalid resource ID filter." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const mcpConfigView of client.mcpConfigs.list()) {\n console.log(mcpConfigView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.mcp_configs.list()\npage = page.mcp_configs[0]\nprint(page.id)" } ] } }, "/v1/mcp-configs/{id}": { "get": { "tags": ["mcp-configs"], "summary": "[Beta] Get an McpConfig.", "description": "[Beta] Get a specific McpConfig by its unique identifier.", "operationId": "getMcpConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the McpConfig.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the McpConfig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "McpConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mcpConfigView = await client.mcpConfigs.retrieve('id');\n\nconsole.log(mcpConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nmcp_config_view = client.mcp_configs.retrieve(\n \"id\",\n)\nprint(mcp_config_view.id)" } ] }, "post": { "tags": ["mcp-configs"], "summary": "[Beta] Update an McpConfig.", "description": "[Beta] Update an existing McpConfig. All fields are optional.", "operationId": "updateMcpConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the McpConfig to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigUpdateParameters" } } } }, "responses": { "200": { "description": "McpConfig updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigView" } } } }, "400": { "description": "Bad request. Invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "McpConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mcpConfigView = await client.mcpConfigs.update('id');\n\nconsole.log(mcpConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nmcp_config_view = client.mcp_configs.update(\n id=\"id\",\n)\nprint(mcp_config_view.id)" } ] } }, "/v1/mcp-configs/{id}/delete": { "post": { "tags": ["mcp-configs"], "summary": "[Beta] Delete an McpConfig.", "description": "[Beta] Delete an existing McpConfig. This action is irreversible.", "operationId": "deleteMcpConfig", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the McpConfig to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "McpConfig deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfigView" } } } }, "400": { "description": "Bad request. Config is in use by active devboxes." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "McpConfig not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mcpConfigView = await client.mcpConfigs.delete('id');\n\nconsole.log(mcpConfigView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nmcp_config_view = client.mcp_configs.delete(\n \"id\",\n)\nprint(mcp_config_view.id)" } ] } }, "/v1/network-policies": { "post": { "tags": ["network-policies"], "summary": "Create a NetworkPolicy.", "description": "Create a new NetworkPolicy with the specified egress rules. The policy can then be applied to blueprints, devboxes, or snapshot resumes.", "operationId": "createNetworkPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyCreateParameters" } } } }, "responses": { "200": { "description": "NetworkPolicy created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyView" } } } }, "400": { "description": "Bad request. Name or egress rules are invalid." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst networkPolicyView = await client.networkPolicies.create({ name: 'name' });\n\nconsole.log(networkPolicyView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nnetwork_policy_view = client.network_policies.create(\n name=\"name\",\n)\nprint(network_policy_view.id)" } ] }, "get": { "tags": ["network-policies"], "summary": "List NetworkPolicies.", "description": "List all NetworkPolicies for the authenticated account.", "operationId": "listNetworkPolicies", "parameters": [ { "name": "name", "in": "query", "description": "Filter by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by ID.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by network policy ID or name.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of NetworkPolicies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyListView" } } } }, "400": { "description": "Invalid resource ID filter." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const networkPolicyView of client.networkPolicies.list()) {\n console.log(networkPolicyView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.network_policies.list()\npage = page.network_policies[0]\nprint(page.id)" } ] } }, "/v1/network-policies/{id}": { "get": { "tags": ["network-policies"], "summary": "Get a NetworkPolicy.", "description": "Get a specific NetworkPolicy by its unique identifier.", "operationId": "getNetworkPolicy", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the NetworkPolicy.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the NetworkPolicy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "NetworkPolicy not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst networkPolicyView = await client.networkPolicies.retrieve('id');\n\nconsole.log(networkPolicyView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nnetwork_policy_view = client.network_policies.retrieve(\n \"id\",\n)\nprint(network_policy_view.id)" } ] }, "post": { "tags": ["network-policies"], "summary": "Update a NetworkPolicy.", "description": "Update an existing NetworkPolicy. All fields are optional - null fields preserve existing values, provided fields replace entirely.", "operationId": "updateNetworkPolicy", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the NetworkPolicy to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyUpdateParameters" } } } }, "responses": { "200": { "description": "NetworkPolicy updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyView" } } } }, "400": { "description": "Bad request. Invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "NetworkPolicy not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst networkPolicyView = await client.networkPolicies.update('id');\n\nconsole.log(networkPolicyView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nnetwork_policy_view = client.network_policies.update(\n id=\"id\",\n)\nprint(network_policy_view.id)" } ] } }, "/v1/network-policies/{id}/delete": { "post": { "tags": ["network-policies"], "summary": "Delete a NetworkPolicy.", "description": "Delete an existing NetworkPolicy. This action is irreversible.", "operationId": "deleteNetworkPolicy", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the NetworkPolicy to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "NetworkPolicy deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyView" } } } }, "400": { "description": "Bad request. Policy is in use by active devboxes." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "NetworkPolicy not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst networkPolicyView = await client.networkPolicies.delete('id');\n\nconsole.log(networkPolicyView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nnetwork_policy_view = client.network_policies.delete(\n \"id\",\n)\nprint(network_policy_view.id)" } ] } }, "/v1/objects": { "post": { "tags": ["objects"], "summary": "Create an Object.", "description": "Create a new Object with content and metadata. The Object will be assigned a unique ID.", "operationId": "createObject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectCreateParameters" } } } }, "responses": { "200": { "description": "Object created successfully. Returns the Object with metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Bad request. Invalid content or parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst objectView = await client.objects.create({ content_type: 'unspecified', name: 'name' });\n\nconsole.log(objectView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nobject_view = client.objects.create(\n content_type=\"unspecified\",\n name=\"name\",\n)\nprint(object_view.id)" } ] }, "get": { "tags": ["objects"], "summary": "List Objects.", "description": "List all Objects for the authenticated account with pagination support.", "operationId": "listObjects", "parameters": [ { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter storage objects by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "description": "Filter storage objects by content type.", "allowEmptyValue": true, "schema": { "$ref": "#/components/schemas/ContentType" } }, { "name": "state", "in": "query", "description": "Filter storage objects by state.", "allowEmptyValue": true, "schema": { "$ref": "#/components/schemas/ObjectState" } }, { "name": "search", "in": "query", "description": "Search by object ID or name.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of Objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectListView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const objectView of client.objects.list()) {\n console.log(objectView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.objects.list()\npage = page.objects[0]\nprint(page.id)" } ] } }, "/v1/objects/list_public": { "get": { "tags": ["objects"], "summary": "List Public Objects.", "description": "List all public Objects with pagination support.", "operationId": "listPublicObjects", "parameters": [ { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "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.", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter storage objects by name (partial match supported).", "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "description": "Filter storage objects by content type.", "allowEmptyValue": true, "schema": { "$ref": "#/components/schemas/ContentType" } }, { "name": "state", "in": "query", "description": "Filter storage objects by state.", "allowEmptyValue": true, "schema": { "$ref": "#/components/schemas/ObjectState" } }, { "name": "search", "in": "query", "description": "Search by object ID or name.", "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.", "allowEmptyValue": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successfully retrieved list of public Objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectListView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const objectView of client.objects.listPublic()) {\n console.log(objectView.id);\n}" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\npage = client.objects.list_public()\npage = page.objects[0]\nprint(page.id)" } ] } }, "/v1/objects/metadata/keys": { "get": { "tags": ["objects"], "summary": "List available object metadata keys.", "description": "Returns a list of all available metadata keys that can be used for filtering objects.", "operationId": "getObjectMetadataKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataKeysView" } } } } } } }, "/v1/objects/metadata/keys/{key}/values": { "get": { "tags": ["objects"], "summary": "List values for a specific object metadata key.", "description": "Returns a list of all values that exist for a specific metadata key across all objects.", "operationId": "getObjectMetadataValues", "parameters": [ { "name": "key", "in": "path", "description": "The metadata key to get values for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValuesView" } } } }, "400": { "description": "Invalid metadata key provided." } } } }, "/v1/objects/{id}": { "get": { "tags": ["objects"], "summary": "Get an Object.", "description": "Retrieve a specific Object by its unique identifier.", "operationId": "getObject", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Object to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Object retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Object not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst objectView = await client.objects.retrieve('id');\n\nconsole.log(objectView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nobject_view = client.objects.retrieve(\n \"id\",\n)\nprint(object_view.id)" } ] } }, "/v1/objects/{id}/complete": { "post": { "tags": ["objects"], "summary": "Complete Object Upload.", "description": "Mark an Object's upload as complete, transitioning it from UPLOADING to READ-only state.", "operationId": "completeObject", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Object to complete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "Object upload completed successfully. Returns the Object with updated state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Object not found." }, "409": { "description": "Object is not in UPLOADING state." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst objectView = await client.objects.complete('id');\n\nconsole.log(objectView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nobject_view = client.objects.complete(\n \"id\",\n)\nprint(object_view.id)" } ] } }, "/v1/objects/{id}/delete": { "post": { "tags": ["objects"], "summary": "Delete an Object.", "description": "Delete an existing Object by ID. This action is irreversible and will remove the Object and all its metadata.", "operationId": "deleteObject", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Object to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "Object deleted successfully. Returns the deleted Object metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Object not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst objectView = await client.objects.delete('id');\n\nconsole.log(objectView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nobject_view = client.objects.delete(\n \"id\",\n)\nprint(object_view.id)" } ] } }, "/v1/objects/{id}/download": { "get": { "tags": ["objects"], "summary": "Generate Download URL for Object.", "description": "Generate a presigned download URL for an Object. The URL will be valid for the specified duration.", "operationId": "generateDownloadUrl", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Object to generate download URL for.", "required": true, "schema": { "type": "string" } }, { "name": "duration_seconds", "in": "query", "description": "Duration in seconds for the presigned URL validity (default: 3600).", "allowEmptyValue": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Download URL generated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectDownloadUrlView" } } } }, "400": { "description": "Bad request. Object is in deleted state or invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Object not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst objectDownloadURLView = await client.objects.download('id');\n\nconsole.log(objectDownloadURLView.download_url);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nobject_download_url_view = client.objects.download(\n id=\"id\",\n)\nprint(object_download_url_view.download_url)" } ] } }, "/v1/restricted_keys": { "post": { "tags": ["restricted_keys"], "summary": "Create a restricted API key.", "description": "Create a restricted API key with specific resource scopes. Use a standard API key (ak_) or a restricted key (rk_) with RESOURCE_TYPE_ACCOUNT write scope.", "operationId": "createRestrictedKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedKeyCreateParameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedKeyCreatedView" } } } }, "400": { "description": "Invalid scopes." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst restrictedKeyCreatedView = await client.restrictedKeys.create();\n\nconsole.log(restrictedKeyCreatedView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nrestricted_key_created_view = client.restricted_keys.create()\nprint(restricted_key_created_view.id)" } ] } }, "/v1/secrets": { "post": { "tags": ["secrets"], "summary": "Create a Secret.", "description": "Create a new Secret with a name and value. The Secret will be encrypted at rest and made available as an environment variable in Devboxes. Creation rejects an existing name within the account on a best-effort basis; concurrent creates may produce duplicates.", "operationId": "createSecret", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreateParameters" } } } }, "responses": { "200": { "description": "Secret created successfully. Returns the Secret without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "400": { "description": "Bad request. Secret name already exists, is invalid, or contains illegal characters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.create({ name: 'name', value: 'value' });\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.create(\n name=\"name\",\n value=\"value\",\n)\nprint(secret_view.id)" } ] }, "get": { "tags": ["secrets"], "summary": "List Secrets.", "description": "List all Secrets for the authenticated account. Secret values are not included for security reasons.", "operationId": "listSecrets", "parameters": [ { "name": "limit", "in": "query", "description": "The limit of items to return. Default is 20. Max is 5000.", "allowEmptyValue": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully retrieved list of Secrets. Values are omitted for security.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretListView = await client.secrets.list();\n\nconsole.log(secretListView.has_more);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_list_view = client.secrets.list()\nprint(secret_list_view.has_more)" } ] } }, "/v1/secrets/id/{id}": { "get": { "tags": ["secrets"], "summary": "Get a Secret by ID.", "description": "Retrieve a Secret by ID. The secret value is not included for security.", "operationId": "getSecretById", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the Secret to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Secret. Value is omitted for security.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "404": { "description": "Secret not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.retrieveById('id');\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.retrieve_by_id(\n \"id\",\n)\nprint(secret_view.id)" } ] } }, "/v1/secrets/id/{id}/delete": { "post": { "tags": ["secrets"], "summary": "Delete a Secret by ID.", "description": "Delete an existing Secret by ID. This action is irreversible.", "operationId": "deleteSecretById", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the Secret to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "Secret deleted successfully. Returns the deleted Secret (without value for security).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Secret not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.deleteById('id');\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.delete_by_id(\n \"id\",\n)\nprint(secret_view.id)" } ] } }, "/v1/secrets/id/{id}/update": { "post": { "tags": ["secrets"], "summary": "Update a Secret by ID.", "description": "Update the value of an existing Secret by ID. The new value will be encrypted at rest.", "operationId": "updateSecretById", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the Secret to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpdateParameters" } } } }, "responses": { "200": { "description": "Secret updated successfully. Returns the Secret without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "400": { "description": "Bad request. Invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Secret not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.updateById('id', { value: 'value' });\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.update_by_id(\n id=\"id\",\n value=\"value\",\n)\nprint(secret_view.id)" } ] } }, "/v1/secrets/{name}": { "get": { "tags": ["secrets"], "summary": "Get a Secret.", "description": "Retrieve a Secret by name. If several match, the greatest ID is selected. The secret value is not included for security.", "operationId": "getSecret", "parameters": [ { "name": "name", "in": "path", "description": "The name of the Secret to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Secret. Value is omitted for security.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "404": { "description": "Secret not found." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.retrieve('name');\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.retrieve(\n \"name\",\n)\nprint(secret_view.id)" } ] }, "post": { "tags": ["secrets"], "summary": "Update a Secret.", "description": "Update the value of an existing Secret by name. If several Secrets in the account have this name, only the one with the greatest ID at lookup is updated and returned. Older matches are unchanged. A concurrent create may become the latest match. The new value will be encrypted at rest.", "operationId": "updateSecret", "parameters": [ { "name": "name", "in": "path", "description": "The name of the Secret to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpdateParameters" } } } }, "responses": { "200": { "description": "Secret updated successfully. Returns the Secret without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "400": { "description": "Bad request. Invalid parameters." }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Secret not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.update('name', { value: 'value' });\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.update(\n name=\"name\",\n value=\"value\",\n)\nprint(secret_view.id)" } ] } }, "/v1/secrets/{name}/delete": { "post": { "tags": ["secrets"], "summary": "Delete a Secret.", "description": "Delete an existing Secret by name. If several Secrets in the account have this name, every selected match is deleted and the one with the greatest selected ID is returned. Deletions are not atomic across matches: a failure may leave some matches deleted. A concurrent create may survive. This action is irreversible.", "operationId": "deleteSecret", "parameters": [ { "name": "name", "in": "path", "description": "The name of the Secret to delete.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRecord" } } } }, "responses": { "200": { "description": "Secret deleted successfully. Returns the deleted Secret (without value for security).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication." }, "403": { "description": "Forbidden. Account does not have devbox capability." }, "404": { "description": "Secret not found." }, "500": { "description": "Internal server error." } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Runloop from '@runloop/api-client';\n\nconst client = new Runloop({\n bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst secretView = await client.secrets.delete('name');\n\nconsole.log(secretView.id);" }, { "lang": "Python", "source": "import os\nfrom runloop_api_client import Runloop\n\nclient = Runloop(\n bearer_token=os.environ.get(\"RUNLOOP_API_KEY\"), # This is the default and can be omitted\n)\nsecret_view = client.secrets.delete(\n \"name\",\n)\nprint(secret_view.id)" } ] } } }, "tags": [ { "name": "Blueprint" }, { "name": "Blueprint-Lifecycle" }, { "name": "Blueprint-ObservabilityTools" }, { "name": "Devbox" }, { "name": "Devbox-FileTools" }, { "name": "Devbox-Lifecycle" }, { "name": "Devbox-NetworkTools" }, { "name": "Devbox-ObservabilityTools" }, { "name": "Devbox-PersistenceTools" }, { "name": "Devbox-ShellTools" }, { "name": "accounts" }, { "name": "agents" }, { "name": "apikeys" }, { "name": "axons" }, { "name": "executions" }, { "name": "gateway-configs" }, { "name": "mcp-configs" }, { "name": "network-policies" }, { "name": "objects" }, { "name": "restricted_keys" }, { "name": "secrets" }, { "name": "streaming" } ] }