Cook Job from Recipe

Create a job from a recipe, applying only the overrides supplied in the request body. Use GET /v1/compute/offers to compare machines against the recipe’s requirements, any intended overrides, and an optional discovery price ceiling before cooking.

Carry the chosen hardware and region constraints into the cook overrides; map discovery’s cpu_count filter to min_cpu_count. For exactly two installed GPUs, set min_gpu_count and max_gpu_count to 2. Omitted fields retain the recipe’s values, so omitting max_gpu_count preserves an existing ceiling; use null to clear it. Use min_gpu_count: 0 and max_gpu_count: 0 for CPU-only hardware and clear any inherited GPU model or VRAM requirements. Conflicting GPU bounds or legacy aliases are rejected after the overrides are merged with the recipe.

A discovery result does not reserve capacity. This request does not accept offer_id or max_hourly_rate_usd as a reservation, price lock, or job spending limit.

POST /v1/job-recipes/{uuid}/cook

Cook Job from Recipe

cURL

curl --request POST \
  --url https://api.dispersed.com/v1/job-recipes/{uuid}/cook \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "cpu_count": 1,
  "min_cpu_count": 1,
  "gpu_count": 1,
  "min_gpu_count": 1,
  "max_gpu_count": 1,
  "gpu_name": "<string>",
  "gpu_registry_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "min_vram_gb": 1,
  "min_ram_gb": 1,
  "min_storage_gb": 1,
  "max_node_count": 123,
  "max_retry_count": 1,
  "max_timeout_assign_ms": 300001,
  "max_timeout_start_ms": 120001,
  "max_timeout_run_ms": 60001,
  "parameters": {
    "parameters": {
      "allowed_ips": [
        "<string>"
      ],
      "env": {},
      "image": "<string>",
      "imagesrc": "<string>",
      "ports": [
        123
      ],
      "sshkey": "<string>",
      "srcdigest": "sha256:2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c",
      "srcrepo": "otoy/zernet-base",
      "srctag": "latest",
      "tag": "<string>",
      "volumes": [
        {
          "image": "<string>",
          "mount": "<string>",
          "tag": "<string>"
        }
      ]
    },
    "type": "docker"
  },
  "allowed_region_codes": []
}
'

201

{
  "object": "job",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "status": "PENDING",
  "task": "BATCH",
  "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": {},
      "image": "<string>",
      "imagesrc": "<string>",
      "ports": [
        123
      ],
      "sshkey": "<string>",
      "srcdigest": "sha256:2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c2f4c6b2c",
      "srcrepo": "otoy/zernet-base",
      "srctag": "latest",
      "tag": "<string>",
      "volumes": [
        {
          "image": "<string>",
          "mount": "<string>",
          "tag": "<string>"
        }
      ]
    },
    "type": "docker"
  },
  "timeout_assign_at_ms": 123,
  "uuid": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "min_cpu_count": 123,
  "min_gpu_count": 123,
  "max_gpu_count": 1,
  "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>"
}

Path Parameters

uuid · string · required

Body

application/json

title · string

Override the job title from the recipe.

description · string | null

Override the job description from the recipe.

task · enum<string>

Override the task type. BATCH jobs run to completion; PERSISTENT jobs run indefinitely.

Available options: BATCH, PERSISTENT

cpu_count · integer

Legacy alias for min_cpu_count.

Required range: x >= 0

min_cpu_count · integer

Override the minimum CPU core count.

Required range: x >= 0

gpu_count · integer

Legacy alias for min_gpu_count.

Required range: x >= 0

min_gpu_count · integer

Override the inclusive minimum total GPUs installed on the assigned node, across all models. Set both GPU bounds to the same value for an exact count. Omission preserves the recipe minimum.

Required range: x >= 0

max_gpu_count · integer | null

Override the inclusive maximum total GPUs installed on the assigned node. Omission preserves the recipe ceiling; null clears it. The merged maximum must be at least the merged minimum. Use both bounds at 0 for CPU-only hardware and clear inherited GPU model or VRAM requirements.

Required range: x >= 0

gpu_name · string | null

Override the GPU name requirement. Cannot be used with gpu_registry_uuid.

gpu_registry_uuid · string<uuid> | null

Override with a specific GPU registry UUID for precise matching. Cannot be used with gpu_name.

min_vram_gb · number

Override the minimum VRAM in GB.

Required range: x >= 0

min_ram_gb · number

Override the minimum RAM in GB.

Required range: x >= 0

min_storage_gb · number

Override the minimum storage in GB.

Required range: x >= 0

max_node_count · number

Override the maximum number of nodes.

max_retry_count · number

Override the maximum retry count.

Required range: x >= 0

max_timeout_assign_ms · number

Override the assignment timeout in milliseconds.

Required range: x >= 300000

max_timeout_start_ms · number

Override the start timeout in milliseconds.

Required range: x >= 120000

max_timeout_run_ms · number | null

Override the run timeout in milliseconds. Required for BATCH tasks, must be null for PERSISTENT tasks.

Required range: x >= 60000

parameters · object

Override the container/execution parameters.

Show child attributes

allowed_region_codes · enum<string>[]

Override the recipe`s allowed_region_codes for this cooked Job.

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

Response

201

application/json

Job created from recipe 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

Legacy alias for min_cpu_count.

gpu_count · number | null · required

Legacy alias for min_gpu_count.

min_ram_gb · number · required

min_vram_gb · number · required

min_storage_gb · number · required

parameters · object · required

Show child attributes

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

min_cpu_count · number | null

Minimum CPU cores required on the node.

min_gpu_count · number | null

Minimum total GPUs required on the node.

max_gpu_count · integer | null

Inclusive maximum total GPUs on the node; null means unlimited.

Required range: x >= 0

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> | null)[]

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, null

Example:

"us-west-2"

container_access_tokens · object[]

Show child attributes

status_reason · string | null

source_recipe_uuid · string | null