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

# Attachments

> Retrieve and export files surfaced by Atlas during sessions and job runs.

Attachments are files surfaced by Atlas during a session or job run. They can be annotated and downloaded via signed export URLs.

## Endpoints

| Method  | Path                                         | Description                |
| ------- | -------------------------------------------- | -------------------------- |
| `GET`   | `/attachments`                               | List attachments           |
| `GET`   | `/attachments/{attachment_uuid}`             | Get attachment details     |
| `PATCH` | `/attachments/{attachment_uuid}`             | Update attachment metadata |
| `POST`  | `/attachments/{attachment_uuid}/export`      | Get a signed download URL  |
| `GET`   | `/attachments/{attachment_uuid}/annotations` | List annotations           |
| `POST`  | `/annotations`                               | Create an annotation       |

***

## List attachments

`GET /attachments`

Returns attachments belonging to the authenticated user and attachments created by Atlas in their sessions.

**Query parameters:**

| Parameter         | Required | Type   | Description                                    |
| ----------------- | -------- | ------ | ---------------------------------------------- |
| `session_id`      | No       | UUID   | Filter to a specific session                   |
| `attachment_type` | No       | string | Filter by file type (e.g. `pdf`, `csv`, `bin`) |
| `created_after`   | No       | string | ISO 8601 datetime lower bound                  |
| `created_before`  | No       | string | ISO 8601 datetime upper bound                  |

**Example request:**

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

Returns `{"items": [...], "count": N}` where each item is an attachment object:

| Field                          | Type    | Nullable | Description                                      |
| ------------------------------ | ------- | -------- | ------------------------------------------------ |
| `attachment_id`                | UUID    | Yes      | Attachment identifier                            |
| `attachment_name`              | string  | No       | Original filename                                |
| `attachment_type`              | string  | No       | File type                                        |
| `attachment_title`             | string  | Yes      | Display title                                    |
| `attachment_description`       | string  | Yes      | Description                                      |
| `attachment_citation`          | string  | Yes      | Source citation                                  |
| `attachment_source_session_id` | UUID    | Yes      | Session this attachment belongs to               |
| `attachment_created_by`        | string  | No       | Creator (email or `"atlas"`)                     |
| `attachment_created_at`        | string  | No       | ISO 8601 creation timestamp                      |
| `is_visible`                   | boolean | No       | Whether the attachment should be shown in the UI |

**Example response:**

```json theme={null}
{
  "items": [
    {
      "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
      "attachment_name": "telemetry.bin",
      "attachment_type": "bin",
      "attachment_title": null,
      "attachment_description": null,
      "attachment_citation": null,
      "attachment_source_session_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
      "attachment_created_by": "engineer@example.com",
      "attachment_created_at": "2026-04-13T10:21:00.000000",
      "is_visible": true
    }
  ],
  "count": 1
}
```

***

## Get attachment details

`GET /attachments/{attachment_uuid}`

Returns a single attachment with its full content payload.

**Example request:**

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

**Response fields:**

| Field                          | Type    | Nullable | Description                                               |
| ------------------------------ | ------- | -------- | --------------------------------------------------------- |
| `attachment_id`                | UUID    | Yes      | Attachment identifier                                     |
| `attachment_name`              | string  | No       | Original filename                                         |
| `attachment_type`              | string  | No       | File type                                                 |
| `attachment_title`             | string  | Yes      | Display title                                             |
| `attachment_description`       | string  | Yes      | Description                                               |
| `attachment_citation`          | string  | Yes      | Source citation                                           |
| `attachment_source_session_id` | UUID    | Yes      | Session this attachment belongs to                        |
| `attachment_created_by`        | string  | No       | Creator (email or `"atlas"`)                              |
| `attachment_created_at`        | string  | No       | ISO 8601 creation timestamp                               |
| `is_visible`                   | boolean | No       | Whether the attachment is shown in the UI                 |
| `attachment_content`           | object  | Yes      | Structured content payload (chart data, table data, etc.) |
| `s3_url`                       | string  | Yes      | S3 URL of the underlying file                             |

**Example response:**

```json theme={null}
{
  "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
  "attachment_name": "telemetry.bin",
  "attachment_type": "bin",
  "attachment_title": null,
  "attachment_description": null,
  "attachment_citation": null,
  "attachment_source_session_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "attachment_created_by": "engineer@example.com",
  "attachment_created_at": "2026-04-13T10:21:00.000000",
  "is_visible": true,
  "attachment_content": null,
  "s3_url": "s3://your-bucket/attachments/telemetry.bin"
}
```

***

## Update attachment metadata

`PATCH /attachments/{attachment_uuid}`

**Request body (all fields optional):**

| Field                    | Type    | Description                               |
| ------------------------ | ------- | ----------------------------------------- |
| `attachment_title`       | string  | Display title                             |
| `attachment_description` | string  | Description                               |
| `attachment_citation`    | string  | Source citation                           |
| `is_visible`             | boolean | Whether the attachment is shown in the UI |

**Example request:**

```bash theme={null}
curl -X PATCH "https://nokia.atlas.arenaphysica.com/api/v1/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attachment_title": "Motor telemetry – test run 42"}'
```

Returns the updated attachment object with the same fields as the [list response](#list-attachments).

***

## Download an attachment

`POST /attachments/{attachment_uuid}/export`

Returns a signed URL for direct download.

**Example request:**

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

**Response fields:**

| Field           | Type   | Nullable | Description                      |
| --------------- | ------ | -------- | -------------------------------- |
| `presigned_url` | string | Yes      | Time-limited signed download URL |

**Example response:**

```json theme={null}
{
  "presigned_url": "https://s3.amazonaws.com/your-bucket/..."
}
```

***

## Create an annotation

`POST /annotations`

Annotations mark regions of interest within an attachment.

**Request body:**

| Field                | Required | Type   | Description                                      |
| -------------------- | -------- | ------ | ------------------------------------------------ |
| `attachment_id`      | Yes      | UUID   | Attachment to annotate                           |
| `annotation_type`    | Yes      | string | Annotation type: `bbox` (bounding box) or `path` |
| `annotation_content` | Yes      | object | Structured annotation content (see below)        |

The `annotation_content` object:

| Field         | Required | Type    | Description                              |
| ------------- | -------- | ------- | ---------------------------------------- |
| `page_width`  | Yes      | number  | Width of the page/image being annotated  |
| `page_height` | Yes      | number  | Height of the page/image being annotated |
| `page_number` | Yes      | integer | Page number (0-indexed)                  |
| `content`     | Yes      | array   | List of bbox or path objects             |

Each bbox object in `content`:

| Field    | Required | Type   | Description                               |
| -------- | -------- | ------ | ----------------------------------------- |
| `tags`   | Yes      | object | Key-value tags (string or boolean values) |
| `label`  | Yes      | string | Annotation label                          |
| `x`      | Yes      | number | Left edge                                 |
| `y`      | Yes      | number | Top edge                                  |
| `width`  | Yes      | number | Box width                                 |
| `height` | Yes      | number | Box height                                |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/annotations" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
    "annotation_type": "bbox",
    "annotation_content": {
      "page_width": 800,
      "page_height": 600,
      "page_number": 0,
      "content": [
        {"tags": {}, "label": "voltage sag region", "x": 120, "y": 45, "width": 200, "height": 80}
      ]
    }
  }'
```

**Response fields:**

| Field                | Type   | Description            |
| -------------------- | ------ | ---------------------- |
| `attachment_id`      | string | Parent attachment      |
| `annotation_id`      | string | Annotation identifier  |
| `annotation_content` | object | The annotation content |
| `annotation_type`    | string | Annotation type        |

**Example response:**

```json theme={null}
{
  "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
  "annotation_id": "d1e2f3a4-b5c6-7890-defa-123456789012",
  "annotation_content": {
    "page_width": 800,
    "page_height": 600,
    "page_number": 0,
    "content": [
      {"tags": {}, "label": "voltage sag region", "x": 120, "y": 45, "width": 200, "height": 80}
    ]
  },
  "annotation_type": "bbox"
}
```

***

## List annotations

`GET /attachments/{attachment_uuid}/annotations`

**Example request:**

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

**Response fields (array):**

| Field                | Type   | Description                |
| -------------------- | ------ | -------------------------- |
| `uuid`               | string | Annotation identifier      |
| `annotation_type`    | string | `bbox` or `path`           |
| `annotation_content` | object | Structured annotation data |
| `attachment_id`      | string | Parent attachment ID       |

**Example response:**

```json theme={null}
[
  {
    "uuid": "d1e2f3a4-b5c6-7890-defa-123456789012",
    "annotation_type": "bbox",
    "annotation_content": {
      "page_width": 800,
      "page_height": 600,
      "page_number": 0,
      "content": [
        {"tags": {}, "label": "voltage sag region", "x": 120, "y": 45, "width": 200, "height": 80}
      ]
    },
    "attachment_id": "f2a3b4c5-d6e7-8901-fabc-012345678901"
  }
]
```