Create a Job

Learn how to create Jobs directly via the API with full control over hardware requirements and container configuration.

Direct Job creation is best for one-off workloads or quick experiments. For workloads you plan to run repeatedly, consider creating a Job Recipe instead — recipes save your configuration and make re-launching easier.

Create Job Request

Endpoint

POST /v1/jobs

Request Body

{
  "task": "PERSISTENT",
  "title": "My GPU Instance",
  "cpu_count": 1,
  "gpu_count": 1,
  "min_ram_gb": 16,
  "min_storage_gb": 32,
  "min_vram_gb": 8,
  "max_timeout_run_ms": null,
  "parameters": {
    "type": "docker",
    "parameters": {
      "image": "otoy/dispersed-base",
      "tag": "latest",
      "sshkey": "ssh-ed25519 AAAA... user@host",
      "allowed_ips": ["0.0.0.0/0"]
    }
  }
}

Hardware Requirements

Field	Type	Description
cpu_count	number	Number of CPU cores
gpu_count	number	Number of GPU devices
min_ram_gb	number	Minimum system RAM in GB
min_storage_gb	number	Minimum available storage in GB
min_vram_gb	number	Minimum GPU VRAM in GB

Container Parameters

Field	Type	Description
image	string	Docker image name
tag	string	Docker image tag
sshkey	string	(Optional) SSH public key for access
allowed_ips	string[]	(Optional) IP addresses allowed to connect

---

Example: Create a BATCH Job

All API requests require HMAC signature authentication. See Authenticate Requests for the generateAuthHeaders helper function used below.

// Using the generateAuthHeaders helper from Authenticate Requests guide
const jobData = {
  task: "BATCH",
  title: "Process Dataset",
  cpu_count: 4,
  gpu_count: 1,
  min_ram_gb: 32,
  min_storage_gb: 100,
  min_vram_gb: 16,
  max_timeout_run_ms: 7200000, // 2 hours
  parameters: {
    type: "docker",
    parameters: {
      image: "myregistry/processor",
      tag: "v1.0",
    },
  },
};

const headers = generateAuthHeaders("POST", "/v1/jobs", {}, jobData);

const response = await fetch("https://api.dispersed.com/v1/jobs", {
  method: "POST",
  headers,
  body: JSON.stringify(jobData),
});

const job = await response.json();
console.log("Job UUID:", job.uuid);
console.log("Status:", job.status);

---

Example: Create a PERSISTENT Job with SSH

const jobData = {
  task: "PERSISTENT",
  title: "Development Environment",
  cpu_count: 2,
  gpu_count: 1,
  min_ram_gb: 16,
  min_storage_gb: 50,
  min_vram_gb: 8,
  max_timeout_run_ms: null, // Required for PERSISTENT
  parameters: {
    type: "docker",
    parameters: {
      image: "otoy/dispersed-base",
      tag: "latest",
      sshkey: "ssh-ed25519 AAAA... user@host",
      allowed_ips: ["0.0.0.0/0"],
    },
  },
};

const headers = generateAuthHeaders("POST", "/v1/jobs", {}, jobData);

const response = await fetch("https://api.dispersed.com/v1/jobs", {
  method: "POST",
  headers,
  body: JSON.stringify(jobData),
});

const job = await response.json();
console.log("Job created:", job.uuid);

---

---

Stop a Job

To stop a RUNNING job (or cancel a PENDING job):

PUT /v1/jobs/{job_uuid}/cancel

{
  "reason": "Optional reason string"
}

---

Best Practices

1. Use Job Recipes for repeated workloads — If you’ll run this configuration again, create a recipe instead of submitting the full payload each time
2. Use BATCH for finite tasks — Set realistic timeouts to prevent runaway costs
3. Use PERSISTENT for interactive work — SSH access, development, debugging
4. Stop PERSISTENT jobs promptly — Set calendar reminders if needed

---

API Reference

For complete API documentation including all fields and response schemas, see the API Reference.