> ## 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.

# Issues

> Create, query, and manage structured findings.

An issue is a problem Atlas has identified — a failure, anomaly, root cause, or action item — with status, priority, and links back to the data it came from. Issues can be created manually or generated automatically by a job run.

See [Generating an Issue](/guides/issues) for a workflow guide.

## Endpoints

| Method   | Path                                       | Description                     |
| -------- | ------------------------------------------ | ------------------------------- |
| `POST`   | `/issues`                                  | Create an issue                 |
| `GET`    | `/issues`                                  | List issues                     |
| `GET`    | `/issues/metrics`                          | Get aggregate metrics           |
| `GET`    | `/issues/{issue_id}`                       | Get an issue                    |
| `PATCH`  | `/issues/{issue_id}`                       | Update an issue                 |
| `DELETE` | `/issues/{issue_id}`                       | Delete an issue                 |
| `GET`    | `/issues/{issue_id}/comments`              | List comments on an issue       |
| `POST`   | `/issues/{issue_id}/comments`              | Add a comment                   |
| `PATCH`  | `/issues/{issue_id}/comments/{comment_id}` | Update a comment                |
| `DELETE` | `/issues/{issue_id}/comments/{comment_id}` | Delete a comment                |
| `GET`    | `/issues/{issue_id}/files`                 | List files attached to an issue |

***

## Create an issue

`POST /issues`

**Request body:**

| Field                | Required | Type            | Description                                                   |
| -------------------- | -------- | --------------- | ------------------------------------------------------------- |
| `title`              | Yes      | string          | Short description of the finding                              |
| `description`        | Yes      | array           | Structured content blocks. Pass `[]` for an empty description |
| `status`             | No       | string          | `open` (default), `in_progress`, `resolved`, `rejected`       |
| `priority`           | No       | string          | `low` (default), `medium`, `high`                             |
| `tags`               | No       | array of string | Labels for categorization                                     |
| `owner`              | No       | string          | Assigned owner. Defaults to `"Unassigned"`                    |
| `resolution_summary` | No       | string          | Summary of how the issue was resolved                         |
| `attachment_ids`     | No       | array of string | UUIDs of attachments to associate                             |
| `session_ids`        | No       | array of string | UUIDs of sessions to associate                                |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/issues" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Power rail undervoltage at startup",
    "description": [],
    "status": "open",
    "priority": "high",
    "tags": ["power", "startup"]
  }'
```

**Response fields:**

| Field                 | Type   | Nullable | Description                                     |
| --------------------- | ------ | -------- | ----------------------------------------------- |
| `uuid`                | string | No       | Issue identifier                                |
| `title`               | string | No       | Issue title                                     |
| `description`         | array  | No       | Structured content blocks                       |
| `status`              | string | Yes      | Current status                                  |
| `priority`            | string | Yes      | Priority level                                  |
| `tags`                | array  | No       | Labels                                          |
| `owner`               | string | No       | Assigned owner                                  |
| `resolution_summary`  | string | Yes      | Resolution notes                                |
| `created_by`          | string | No       | Creator (email or `"Atlas"` for auto-generated) |
| `created_at`          | string | No       | ISO 8601 creation timestamp                     |
| `sessions`            | array  | No       | Associated sessions                             |
| `attachments`         | array  | No       | Directly attached files                         |
| `session_attachments` | array  | No       | Files from associated sessions                  |
| `job_run_id`          | string | Yes      | Job run that generated this issue               |

**Example response:**

```json theme={null}
{
  "uuid": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "title": "Power rail undervoltage at startup",
  "description": [],
  "status": "open",
  "priority": "high",
  "tags": ["power", "startup"],
  "owner": "Unassigned",
  "resolution_summary": null,
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:30:00.000000",
  "sessions": [],
  "attachments": [],
  "session_attachments": [],
  "job_run_id": null
}
```

***

## List issues

`GET /issues`

**Query parameters:**

| Parameter  | Type                | Description                                                                                       |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `status`   | string (repeatable) | Filter by status: `open`, `in_progress`, `resolved`, `rejected`. Pass multiple times to match any |
| `priority` | string (repeatable) | Filter by priority: `low`, `medium`, `high`. Pass multiple times to match any                     |
| `limit`    | integer             | Default `100`, max `1000`                                                                         |
| `offset`   | integer             | Default `0`                                                                                       |

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/issues?status=open&priority=high" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

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

***

## Get an issue

`GET /issues/{issue_id}`

**Example request:**

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

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

***

## Update an issue

`PATCH /issues/{issue_id}`

All fields are optional. Only provided fields are updated.

| Field                | Type            | Description                                   |
| -------------------- | --------------- | --------------------------------------------- |
| `title`              | string          | Updated title                                 |
| `status`             | string          | `open`, `in_progress`, `resolved`, `rejected` |
| `priority`           | string          | `low`, `medium`, `high`                       |
| `tags`               | array of string | Replaces existing tags                        |
| `owner`              | string          | Assigned owner                                |
| `resolution_summary` | string          | Resolution notes                              |

**Example request:**

```bash theme={null}
curl -X PATCH "https://nokia.atlas.arenaphysica.com/api/v1/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress", "owner": "engineer@example.com"}'
```

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

***

## Delete an issue

`DELETE /issues/{issue_id}`

**Example request:**

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

Returns **204 No Content**.

***

## Get metrics

`GET /issues/metrics`

Returns aggregate issue counts broken down by status, rendered as chart-ready data.

**Example request:**

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

**Response fields:**

| Field     | Type  | Description           |
| --------- | ----- | --------------------- |
| `metrics` | array | List of chart objects |

Each chart object:

| Field        | Type   | Description                  |
| ------------ | ------ | ---------------------------- |
| `chart_type` | string | `pie_chart` or `mixed_chart` |
| `chart_data` | object | Chart-specific data payload  |

Pie chart `chart_data`:

| Field            | Type   | Description                             |
| ---------------- | ------ | --------------------------------------- |
| `title`          | string | Chart title                             |
| `data`           | array  | List of `{label, value, color}` objects |
| `colors`         | object | Color overrides (nullable)              |
| `display_config` | object | Display options (nullable)              |

**Example response:**

```json theme={null}
{
  "metrics": [
    {
      "chart_type": "pie_chart",
      "chart_data": {
        "title": "Active Issues",
        "data": [
          {"label": "high", "value": 5, "color": null},
          {"label": "medium", "value": 3, "color": null},
          {"label": "low", "value": 1, "color": null}
        ],
        "colors": null,
        "display_config": null
      }
    }
  ]
}
```

***

## List comments

`GET /issues/{issue_id}/comments`

**Query parameters:**

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `limit`   | integer | Default `50`, max `1000` |
| `offset`  | integer | Default `0`              |

**Example request:**

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

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

***

## Add a comment

`POST /issues/{issue_id}/comments`

**Request body:**

| Field            | Required | Type            | Description                        |
| ---------------- | -------- | --------------- | ---------------------------------- |
| `content`        | Yes      | string          | Comment text (1–10,000 characters) |
| `attachment_ids` | No       | array of string | Up to 10 attachment UUIDs          |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/issues/$ISSUE_ID/comments" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Reproduced on bench. Voltage sag starts at C12. Isolating now."}'
```

**Response fields:**

| Field         | Type    | Nullable | Description                      |
| ------------- | ------- | -------- | -------------------------------- |
| `uuid`        | string  | No       | Comment identifier               |
| `content`     | string  | No       | Comment text                     |
| `attachments` | array   | No       | Attached files                   |
| `created_by`  | string  | No       | Author email                     |
| `created_at`  | string  | No       | ISO 8601 creation timestamp      |
| `updated_at`  | string  | No       | ISO 8601 last-update timestamp   |
| `is_edited`   | boolean | No       | `true` if updated after creation |
| `is_deleted`  | boolean | No       | Soft-delete flag                 |
| `reactions`   | array   | No       | Emoji reaction summaries         |

**Example response:**

```json theme={null}
{
  "uuid": "e1f2a3b4-c5d6-7890-efab-901234567890",
  "content": "Reproduced on bench. Voltage sag starts at C12. Isolating now.",
  "attachments": [],
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:32:00.000000",
  "updated_at": "2026-04-13T10:32:00.000000",
  "is_edited": false,
  "is_deleted": false,
  "reactions": []
}
```

***

## Update a comment

`PATCH /issues/{issue_id}/comments/{comment_id}`

**Request body:**

| Field     | Required | Type   | Description          |
| --------- | -------- | ------ | -------------------- |
| `content` | Yes      | string | Updated comment text |

**Example request:**

```bash theme={null}
curl -X PATCH "https://nokia.atlas.arenaphysica.com/api/v1/issues/$ISSUE_ID/comments/$COMMENT_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Confirmed C12 is root cause. Ordering replacement."}'
```

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

***

## Delete a comment

`DELETE /issues/{issue_id}/comments/{comment_id}`

**Example request:**

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

Returns **204 No Content**.

***

## List issue files

`GET /issues/{issue_id}/files`

Returns files associated with an issue (e.g. troubleshooting plans).

**Query parameters:**

| Parameter   | Type   | Description                                       |
| ----------- | ------ | ------------------------------------------------- |
| `file_type` | string | Filter by file type (e.g. `troubleshooting_plan`) |

**Example request:**

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

**Response fields (array):**

| Field           | Type   | Description                             |
| --------------- | ------ | --------------------------------------- |
| `uuid`          | string | File record identifier                  |
| `file_name`     | string | Display name                            |
| `file_type`     | string | File type (e.g. `troubleshooting_plan`) |
| `attachment_id` | string | Associated attachment identifier        |
| `created_at`    | string | ISO 8601 creation timestamp             |

**Example response:**

```json theme={null}
[
  {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "file_name": "troubleshooting_plan.md",
    "file_type": "troubleshooting_plan",
    "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
    "created_at": "2026-04-13T10:35:00.000000"
  }
]
```