Skip to main content
POST
/
v1
/
jobs
Create Job
curl --request POST \
  --url https://api.dispersed.com/v1/jobs \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": {
    "parameters": {
      "allowed_ips": [
        "<string>"
      ],
      "env": {},
      "host": "<string>",
      "image": "<string>",
      "imagesrc": "<string>",
      "ports": [
        123
      ],
      "secret": "<string>",
      "sshkey": "<string>",
      "tag": "<string>",
      "user": "<string>",
      "volumes": [
        {
          "image": "<string>",
          "mount": "<string>",
          "registry": "<string>",
          "secret": "<string>",
          "tag": "<string>",
          "user": "<string>"
        }
      ]
    }
  },
  "title": "<string>",
  "max_timeout_run_ms": 900000,
  "cpu_count": 4,
  "description": "<string>",
  "gpu_count": 1,
  "gpu_name": "NVIDIA RTX 4090",
  "gpu_registry_uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "max_node_count": 1,
  "max_retry_count": 0,
  "max_timeout_assign_ms": 300000,
  "max_timeout_start_ms": 300000,
  "min_ram_gb": 0,
  "min_storage_gb": 0,
  "min_vram_gb": 0,
  "allowed_region_codes": [
    "us-west-2"
  ]
}
'
{
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "title": "<string>",
  "cpu_count": 123,
  "gpu_count": 123,
  "min_ram_gb": 123,
  "min_vram_gb": 123,
  "min_storage_gb": 123,
  "parameters": {
    "parameters": {
      "allowed_ips": [
        "<string>"
      ],
      "env": {},
      "host": "<string>",
      "image": "<string>",
      "imagesrc": "<string>",
      "ports": [
        123
      ],
      "secret": "<string>",
      "sshkey": "<string>",
      "tag": "<string>",
      "user": "<string>",
      "volumes": [
        {
          "image": "<string>",
          "mount": "<string>",
          "registry": "<string>",
          "secret": "<string>",
          "tag": "<string>",
          "user": "<string>"
        }
      ]
    }
  },
  "timeout_assign_at_ms": 123,
  "uuid": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "gpu_name": "<string>",
  "gpu_registry_uuid": "<string>",
  "max_timeout_assign_ms": 123,
  "max_timeout_run_ms": 123,
  "max_timeout_start_ms": 123,
  "max_retry_count": 123,
  "max_node_count": 123,
  "image_size_bytes": 123,
  "allowed_region_codes": [],
  "container_access_tokens": [],
  "status_reason": "<string>",
  "source_recipe_uuid": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://otoyinc.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Body

application/json
​
parameters
object
required
​
title
string
required
​
max_timeout_run_ms
number
required

The maximum time in milliseconds to execute a BATCH Job.

Required range: x >= 60000
Example:

900000

​
task
enum<string>
required
Available options:
BATCH
​
cpu_count
number
default:0

The number of CPU cores required for the Job. The assigned Node must have at least this many CPU cores available.

Required range: x >= 0
Example:

4

​
description
string | null

An optional description for the Job.

​
gpu_count
number
default:0

The number of GPUs required for the Job. The assigned Node must have at least this many GPUs available.

Required range: x >= 0
Example:

1

​
gpu_name
string | null

The name of the GPU to use for the Job. If not specified, the system will choose the first available GPU that satisfies the Job requirements. Mutually exclusive with gpu_registry_uuid.

Example:

"NVIDIA RTX 4090"

​
gpu_registry_uuid
string<uuid> | null

UUID of a GPU from the GpuRegistry for exact GPU targeting. Mutually exclusive with gpu_name.

Example:

"01234567-89ab-cdef-0123-456789abcdef"

​
max_node_count
number
default:1

The maximum number of Nodes that can be assigned to run the Job. Default is 1.

​
max_retry_count
number
default:0

The maximum number of times to retry the Job if it fails. Default is 0 (no retries).

Required range: x >= 0
​
max_timeout_assign_ms
number
default:300000

The maximum time in milliseconds to wait for the the Job to be assigned to a Node. Default: 5 minutes.

Required range: x >= 300000
​
max_timeout_start_ms
number
default:300000

The maximum time in milliseconds to wait for the the Node to finish preparing the assigned Job. Default: 5 minutes.

Required range: x >= 120000
​
min_ram_gb
number
default:0

The minimum RAM in gigabytes required for the Job. The assigned Node must have at least this much RAM available.

Required range: x >= 0
​
min_storage_gb
number
default:0

The minimum storage in gigabytes required for the Job. The assigned Node must have at least this much storage available.

Required range: x >= 0
​
min_vram_gb
number
default:0

The minimum VRAM in gigabytes required for the Job. The assigned Node must have at least this much VRAM available.

Required range: x >= 0
​
allowed_region_codes
enum<string>[]

Restrict this Job to nodes in the given region codes. Empty = no per-Job restriction.

Maximum array length: 36
Available options:
ca-central-1,
ca-west-1,
mx-central-1,
sa-east-1,
us-east-1,
us-east-2,
us-west-1,
us-west-2,
eu-central-1,
eu-central-2,
eu-north-1,
eu-south-1,
eu-south-2,
eu-west-1,
eu-west-2,
eu-west-3,
ap-east-1,
ap-east-2,
ap-northeast-1,
ap-northeast-2,
ap-northeast-3,
ap-south-1,
ap-south-2,
ap-southeast-1,
ap-southeast-2,
ap-southeast-3,
ap-southeast-4,
ap-southeast-5,
ap-southeast-6,
ap-southeast-7,
cn-north-1,
cn-northwest-1,
af-south-1,
il-central-1,
me-central-1,
me-south-1
Example:
["us-west-2"]

Response

Job created successfully

​
object
enum<string>
required
Available options:
job
​
created_at
string<date-time> | null
required
​
updated_at
string<date-time> | null
required
​
status
enum<string>
required
Available options:
PENDING,
ASSIGNED,
RUNNING,
COMPLETED,
CANCELLED,
FAILED
​
task
enum<string>
required
Available options:
BATCH,
PERSISTENT
​
title
string
required
​
cpu_count
number | null
required
​
gpu_count
number | null
required
​
min_ram_gb
number
required
​
min_vram_gb
number
required
​
min_storage_gb
number
required
​
parameters
object
required
​
timeout_assign_at_ms
number | null
required
​
uuid
string | null
​
started_at
string<date-time> | null
​
completed_at
string<date-time> | null
​
description
string | null
​
gpu_name
string | null
​
gpu_registry_uuid
string | null
​
max_timeout_assign_ms
number | null
​
max_timeout_run_ms
number | null
​
max_timeout_start_ms
number | null
​
max_retry_count
number | null
​
max_node_count
number | null
​
image_size_bytes
number | null
​
allowed_region_codes
enum<string>[]

Coarse geographic-network region identifier (AWS-style naming).

Available options:
ca-central-1,
ca-west-1,
mx-central-1,
sa-east-1,
us-east-1,
us-east-2,
us-west-1,
us-west-2,
eu-central-1,
eu-central-2,
eu-north-1,
eu-south-1,
eu-south-2,
eu-west-1,
eu-west-2,
eu-west-3,
ap-east-1,
ap-east-2,
ap-northeast-1,
ap-northeast-2,
ap-northeast-3,
ap-south-1,
ap-south-2,
ap-southeast-1,
ap-southeast-2,
ap-southeast-3,
ap-southeast-4,
ap-southeast-5,
ap-southeast-6,
ap-southeast-7,
cn-north-1,
cn-northwest-1,
af-south-1,
il-central-1,
me-central-1,
me-south-1
​
container_access_tokens
object[]
​
status_reason
string | null
​
source_recipe_uuid
string | null