Skip to content
Dreadnode Dreadnode Dreadnode

Create runtime

POST
/api/v1/org/{org}/ws/{workspace}/runtimes
 
curl --request POST \
  --url https://example.com/api/v1/org/example/ws/example/runtimes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "config": { "build": { "profile": "default", "provider": "auto", "source": { "kind": "builtin", "ref": "runtime" } }, "capabilities": [ { "enabled": true, "name": "example", "version": "example" } ], "defaults": { "agent": "example", "capability": "example", "model": "example", "system_prompt": "example" }, "metadata": { "labels": { "additionalProperty": "example" } }, "resources": { "cpu_cores": 2, "memory_mb": 2048 }, "runtime_server": { "env": { "additionalProperty": "example" } }, "sandbox": { "exposed_ports": [ 1 ], "timeout_seconds": 1, "workspace_mount": true }, "secrets": { "secret_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }, "version": "v2" }, "description": "example", "key": "example", "name": "example", "project": "example" }'

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
org
required
Org

Organization slug

string

Organization slug

workspace
required
Workspace

Workspace slug

string

Workspace slug

Request Body required

Section titled “Request Body required ”
Media type application/json
RuntimeCreateRequest

Inputs for creating a durable runtime in a workspace.

object
config
Any of:
RuntimeConfig
object
build
RuntimeConfigBuild
object
profile
Profile
string
default: default >= 1 characters
provider
Provider
string
default: auto
Allowed values: auto docker e2b
source
RuntimeConfigBuildSource
object
kind
Kind
string
default: builtin >= 1 characters
ref
Ref
string
default: runtime >= 1 characters
capabilities
Capabilities
Array<object>
RuntimeConfigCapability
object
enabled
Enabled
boolean
default: true
name
required
Name
string
>= 1 characters
version
Any of:
string
>= 1 characters
defaults
RuntimeConfigDefaults
object
agent
Any of:
string
>= 1 characters
capability
Any of:
string
>= 1 characters
model
Any of:
string
>= 1 characters
system_prompt
Any of:
string
metadata
RuntimeConfigMetadata
object
labels
Labels
object
key
additional properties
string
resources
RuntimeConfigResources
object
cpu_cores
Cpu Cores
integer
default: 2 >= 1 <= 32
memory_mb
Memory Mb
integer
default: 2048 >= 512 <= 131072
runtime_server
RuntimeConfigRuntimeServer
object
env
Env
object
key
additional properties
string
sandbox
RuntimeConfigSandbox
object
exposed_ports
Exposed Ports
Array<integer>
timeout_seconds
Any of:
integer
>= 60
workspace_mount
Workspace Mount
boolean
default: true
secrets
RuntimeConfigSecrets
object
secret_ids
Secret Ids
Array<string>
version
Version
string
default: v2
Allowed value: v2
description
Any of:
string
<= 500 characters
key
Any of:
string
>= 1 characters
name
Any of:
string
>= 1 characters <= 100 characters
project
Any of:
string
>= 1 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Runtime already existed

Media type application/json
RuntimeCreateResponse

Response for idempotent runtime creation.

object
config_digest
required
Config Digest
string
config_version
required
Config Version
string
created
required
Created
boolean
created_at
required
Created At
string format: date-time
description
Any of:
string
id
required
Id
string format: uuid
instance
Any of:
RuntimeInstanceData

Current sandbox materialization for a durable runtime.

object
billed_credits
Billed Credits
integer
0
created_at
required
Created At
string format: date-time
estimated_total_credits
Estimated Total Credits
integer
0
expires_at
Any of:
string format: date-time
pause_reason
Any of:
string
Allowed values: timeout user insufficient_credits member_limit_exceeded
provider
required
Provider
string
provider_sandbox_id
required
Provider Sandbox Id
string
running_credits
Running Credits
integer
0
sandbox_id
required
Sandbox Id
string format: uuid
sandbox_url
Any of:
string
state
required
State
string
Allowed values: running paused killed
total_runtime_seconds
required
Total Runtime Seconds
integer
key
required
Key
string
name
required
Name
string
project_id
required
Any of:
string format: uuid
project_key
Any of:
string
project_name
Any of:
string
status
required
Status
string
Allowed values: idle running paused
updated_at
required
Updated At
string format: date-time
workspace_id
required
Workspace Id
string format: uuid
Example 
{
  "instance": {
    "billed_credits": 0,
    "estimated_total_credits": 0,
    "pause_reason": "timeout",
    "running_credits": 0,
    "state": "running"
  },
  "status": "idle"
}

201

Section titled “201 ”

Successful Response

Media type application/json
RuntimeCreateResponse

Response for idempotent runtime creation.

object
config_digest
required
Config Digest
string
config_version
required
Config Version
string
created
required
Created
boolean
created_at
required
Created At
string format: date-time
description
Any of:
string
id
required
Id
string format: uuid
instance
Any of:
RuntimeInstanceData

Current sandbox materialization for a durable runtime.

object
billed_credits
Billed Credits
integer
0
created_at
required
Created At
string format: date-time
estimated_total_credits
Estimated Total Credits
integer
0
expires_at
Any of:
string format: date-time
pause_reason
Any of:
string
Allowed values: timeout user insufficient_credits member_limit_exceeded
provider
required
Provider
string
provider_sandbox_id
required
Provider Sandbox Id
string
running_credits
Running Credits
integer
0
sandbox_id
required
Sandbox Id
string format: uuid
sandbox_url
Any of:
string
state
required
State
string
Allowed values: running paused killed
total_runtime_seconds
required
Total Runtime Seconds
integer
key
required
Key
string
name
required
Name
string
project_id
required
Any of:
string format: uuid
project_key
Any of:
string
project_name
Any of:
string
status
required
Status
string
Allowed values: idle running paused
updated_at
required
Updated At
string format: date-time
workspace_id
required
Workspace Id
string format: uuid
Example 
{
  "instance": {
    "billed_credits": 0,
    "estimated_total_credits": 0,
    "pause_reason": "timeout",
    "running_credits": 0,
    "state": "running"
  },
  "status": "idle"
}

400

Section titled “400 ”

Invalid request

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

401

Section titled “401 ”

Authentication failed

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

403

Section titled “403 ”

Access forbidden

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

404

Section titled “404 ”

Not found

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

409

Section titled “409 ”

Already exists

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

422

Section titled “422 ”

Validation error

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

426

Section titled “426 ”

Upgrade required

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

429

Section titled “429 ”

Rate limited

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

500

Section titled “500 ”

Internal server error

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

502

Section titled “502 ”

Bad gateway

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}

504

Section titled “504 ”

Gateway timeout

Media type application/json
APIErrorPayload

Canonical API error envelope returned by the API.

object
code
required
Code

HTTP status code

integer
Allowed values: 400 401 403 404 409 422 426 429 500 502 504
detail
required
Detail

Human-readable error message

string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc

Where the validation error occurred

Array
msg
required
Msg

Human-readable validation message

string
type
required
Type

Machine-readable validation error type

string
type
required
Type

Stable machine-readable error type

string
Allowed values: already_exists_error app_error authentication_error conflict_error aws_error configuration_error database_error dynamodb_error e2b_error e2b_rate_limit_error expired_signature_error expired_token_error forbidden_error group_error invalid_error invalid_flag_error invalid_username_error mail_error member_exists_error member_limit_exceeded_error migration_lock_timeout_error not_found_error oauth_config_error org_sandbox_capacity_exceeded_error bad_gateway_error gateway_timeout_error s3_error server_error task_error stripe_error token_error upgrade_required_error usage_limit_exceeded_error user_verification_error validation_error
Example 
{
  "code": 401,
  "detail": "Authentication failed",
  "type": "authentication_error"
}