> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nokia.atlas.arenaphysica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Create and run async AI workflows.

A **Job** is a saved configuration for an async unit of AI work. A **Job Run** is a single execution of that job with its own status, timestamps, and output.

## Endpoints

| Method   | Path                            | Description                                 |
| -------- | ------------------------------- | ------------------------------------------- |
| `GET`    | `/jobs/schemas`                 | List available job types and config schemas |
| `POST`   | `/jobs`                         | Create a job                                |
| `GET`    | `/jobs`                         | List jobs                                   |
| `GET`    | `/jobs/{job_id}`                | Get a job                                   |
| `GET`    | `/jobs/{job_id}/latest-run`     | Get the most recent run for a job           |
| `PATCH`  | `/jobs/{job_id}`                | Update a job                                |
| `DELETE` | `/jobs/{job_id}`                | Delete a job                                |
| `POST`   | `/job-runs`                     | Trigger a job run                           |
| `GET`    | `/job-runs`                     | List job runs                               |
| `GET`    | `/job-runs/{job_run_id}`        | Get a job run                               |
| `POST`   | `/job-runs/{job_run_id}/cancel` | Cancel a running or pending job run         |

***

## Get job schemas

`GET /jobs/schemas`

Returns all available job types with their full config schemas and field descriptions.

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/jobs/schemas" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

**Response fields (array of objects):**

| Field                     | Type    | Description                                                  |
| ------------------------- | ------- | ------------------------------------------------------------ |
| `job_type`                | string  | Job type identifier (use this as `job_type` in `POST /jobs`) |
| `display_name`            | string  | Human-readable name shown in the UI                          |
| `description`             | string  | Internal description of what the job does                    |
| `user_facing_description` | string  | User-facing description                                      |
| `json_schema`             | object  | Full JSON Schema for the `config` field when creating a job  |
| `creatable_on_ui`         | boolean | Whether users can create this job type from the UI           |
| `creatable_by_agent`      | boolean | Whether Atlas can create this job type automatically         |
| `visible_on_ui`           | boolean | Whether this job type appears in the UI                      |

**Example response:**

```json theme={null}
[
  {
    "job_type": "metagraph_update",
    "display_name": "Metagraph Update",
    "description": "Updates the system metagraph based on uploaded documents.",
    "user_facing_description": "Analyzes uploaded documents and updates the system graph.",
    "json_schema": {
      "type": "object",
      "properties": {
        "job_type": {"type": "string"},
        "system_id_or_name": {"type": "string"},
        "additional_context": {"type": "string"}
      },
      "required": ["job_type", "system_id_or_name"]
    },
    "creatable_on_ui": true,
    "creatable_by_agent": true,
    "visible_on_ui": true
  }
]
```

***

## Create a job

`POST /jobs`

**Request body:**

| Field               | Required | Type   | Description                                                                    |
| ------------------- | -------- | ------ | ------------------------------------------------------------------------------ |
| `job_type`          | Yes      | string | Job type identifier (e.g. `metagraph_update`, `generate_issue`)                |
| `config`            | No       | object | Job-type-specific config. Must include `job_type` matching the top-level field |
| `source_session_id` | No       | UUID   | Associate this job with a session                                              |
| `source_project_id` | No       | UUID   | Associate this job with a project                                              |

<Note>
  Use `GET /jobs/schemas` to retrieve the full config schema for a job type before creating a job.
</Note>

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/jobs" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "metagraph_update",
    "config": {
      "job_type": "metagraph_update",
      "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "additional_context": "Focus on the power distribution subsystem"
    }
  }'
```

**Response fields:**

| Field               | Type    | Nullable | Description                     |
| ------------------- | ------- | -------- | ------------------------------- |
| `uuid`              | UUID    | No       | Job identifier                  |
| `name`              | string  | No       | Auto-generated job name         |
| `description`       | string  | Yes      | Job description                 |
| `config`            | object  | No       | Full config object for this job |
| `is_deleted`        | boolean | No       | Soft-delete flag                |
| `created_by`        | string  | No       | Creator email                   |
| `created_at`        | string  | No       | ISO 8601 creation timestamp     |
| `updated_at`        | string  | Yes      | ISO 8601 last-update timestamp  |
| `source_session_id` | UUID    | Yes      | Associated session              |
| `source_project_id` | UUID    | Yes      | Associated project              |

**Example response:**

```json theme={null}
{
  "uuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "name": "metagraph_update – Power Distribution Unit",
  "description": null,
  "config": {
    "job_type": "metagraph_update",
    "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "additional_context": "Focus on the power distribution subsystem"
  },
  "is_deleted": false,
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:10:00.000000",
  "updated_at": null,
  "source_session_id": null,
  "source_project_id": null
}
```

***

## List jobs

`GET /jobs`

**Query parameters:**

| Parameter            | Type                | Description              |
| -------------------- | ------------------- | ------------------------ |
| `job_types`          | string (repeatable) | Filter by job type       |
| `created_by_users`   | string (repeatable) | Filter by creator email  |
| `source_session_ids` | UUID (repeatable)   | Filter by source session |
| `created_after`      | string              | ISO 8601 lower bound     |
| `created_before`     | string              | ISO 8601 upper bound     |

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/jobs" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns `{"items": [...], "count": N}` where each item is a job object with the same fields as the [create response](#create-a-job).

***

## Get a job

`GET /jobs/{job_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a job object with the same fields as the [create response](#create-a-job).

***

## Get latest run

`GET /jobs/{job_id}/latest-run`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID/latest-run" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns the most recent job run object with the same fields as the [trigger response](#trigger-a-job-run). Returns **204 No Content** if the job has no runs yet.

***

## Update a job

`PATCH /jobs/{job_id}`

All fields are optional.

| Field    | Type   | Description        |
| -------- | ------ | ------------------ |
| `config` | object | Updated job config |

**Example request:**

```bash theme={null}
curl -X PATCH "https://nokia.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {"job_type": "metagraph_update", "additional_context": "Focus on power rail issues"}}'
```

Returns the updated job object with the same fields as the [create response](#create-a-job).

***

## Delete a job

`DELETE /jobs/{job_id}`

Soft-deletes a job.

**Example request:**

```bash theme={null}
curl -X DELETE "https://nokia.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

**Example response:**

```json theme={null}
{
  "message": "Job d4e5f6a7-b8c9-0123-defa-234567890123 soft deleted"
}
```

***

## Trigger a job run

`POST /job-runs`

**Request body:**

| Field    | Required | Type   | Description              |
| -------- | -------- | ------ | ------------------------ |
| `job_id` | Yes      | UUID   | ID of the job to run     |
| `config` | No       | object | Runtime config overrides |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/job-runs" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "d4e5f6a7-b8c9-0123-defa-234567890123"}'
```

**Response fields:**

| Field               | Type    | Nullable | Description                                |
| ------------------- | ------- | -------- | ------------------------------------------ |
| `uuid`              | UUID    | No       | Job run identifier                         |
| `job_id`            | UUID    | No       | Parent job                                 |
| `job_name`          | string  | No       | Name of the parent job                     |
| `config`            | object  | No       | Config used for this run                   |
| `status`            | string  | No       | Current run status (see below)             |
| `created_by`        | string  | No       | Creator email                              |
| `created_at`        | string  | No       | ISO 8601 creation timestamp                |
| `updated_at`        | string  | No       | ISO 8601 last-update timestamp             |
| `is_deleted`        | boolean | No       | Soft-delete flag                           |
| `output_references` | array   | No       | References to outputs produced by this run |

**Job run status values:**

| Value       | Description               |
| ----------- | ------------------------- |
| `pending`   | Queued, not yet started   |
| `running`   | Currently executing       |
| `paused`    | Execution paused          |
| `completed` | Finished successfully     |
| `failed`    | Encountered an error      |
| `cancelled` | Stopped before completion |

**Example response:**

```json theme={null}
{
  "uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "job_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "job_name": "metagraph_update – Power Distribution Unit",
  "config": {
    "job_type": "metagraph_update",
    "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "status": "pending",
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:11:00.000000",
  "updated_at": "2026-04-13T10:11:00.000000",
  "is_deleted": false,
  "output_references": []
}
```

***

## Get a job run

`GET /job-runs/{job_run_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/job-runs/$JOB_RUN_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a job run object with the same fields as the [trigger response](#trigger-a-job-run). Poll this endpoint until `status` reaches `completed`, `failed`, or `cancelled`.

***

## List job runs

`GET /job-runs`

**Query parameters:**

| Parameter        | Type                | Description                       |
| ---------------- | ------------------- | --------------------------------- |
| `job_id`         | UUID                | Filter to runs for a specific job |
| `job_types`      | string (repeatable) | Filter by job type                |
| `statuses`       | string (repeatable) | Filter by status                  |
| `created_after`  | string              | ISO 8601 lower bound              |
| `created_before` | string              | ISO 8601 upper bound              |

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/job-runs?job_id=$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns `{"items": [...], "count": N}` where each item is a job run object with the same fields as the [trigger response](#trigger-a-job-run).

***

## Cancel a job run

`POST /job-runs/{job_run_id}/cancel`

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/job-runs/$JOB_RUN_ID/cancel" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

**Response fields:**

| Field             | Type    | Description               |
| ----------------- | ------- | ------------------------- |
| `message`         | string  | Confirmation message      |
| `cancelled_count` | integer | Number of tasks cancelled |

**Example response:**

```json theme={null}
{
  "message": "Job run e5f6a7b8-c9d0-1234-efab-345678901234 cancelled",
  "cancelled_count": 1
}
```