> ## Documentation Index
> Fetch the complete documentation index at: https://otoyinc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Job

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

<Note>
  Direct Job creation is best for **one-off workloads** or quick experiments. For workloads you plan to run repeatedly, consider creating a [Job Recipe](/service-consumers/service-consumers-quick-start-job-recipe) instead — recipes save your configuration and make re-launching easier.
</Note>

## Create Job Request

### Endpoint

```http theme={null}
POST /v1/jobs
```

### Request Body

```json theme={null}
{
  "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

<Note>
  All API requests require HMAC signature authentication. See [Authenticate Requests](/service-consumers/service-consumers-authenticate-requests) for the `generateAuthHeaders` helper function used below.
</Note>

```javascript theme={null}
// 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

```javascript theme={null}
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):

```http theme={null}
PUT /v1/jobs/{job_uuid}/cancel
```

```json theme={null}
{
  "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](/api-reference).