Attachments

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:

curl "https://spacex.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:

{
  "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:

curl "https://spacex.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:

{
  "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:

curl -X PATCH "https://spacex.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.

Download an attachment

POST /attachments/{attachment_uuid}/export Returns a signed URL for direct download. Example request:

curl -X POST "https://spacex.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:

{
  "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:

curl -X POST "https://spacex.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:

{
  "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:

curl "https://spacex.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:

[
  {
    "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"
  }
]

Overview

Resources

Endpoints

List attachments

Get attachment details

Update attachment metadata

Download an attachment

Create an annotation

List annotations

Overview

Resources

​Endpoints

​List attachments

​Get attachment details

​Update attachment metadata

​Download an attachment

​Create an annotation

​List annotations

Endpoints

List attachments

Get attachment details

Update attachment metadata

Download an attachment

Create an annotation

List annotations