Issues

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

curl -X POST "$ATLAS_URL/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:

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

curl "$ATLAS_URL/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.

Get an issue

GET /issues/{issue_id} Example request:

curl "$ATLAS_URL/api/v1/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a single issue object with the same fields as the create response.

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:

curl -X PATCH "$ATLAS_URL/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.

Delete an issue

DELETE /issues/{issue_id} Example request:

curl -X DELETE "$ATLAS_URL/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:

curl "$ATLAS_URL/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:

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

curl "$ATLAS_URL/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

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:

curl -X POST "$ATLAS_URL/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:

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

curl -X PATCH "$ATLAS_URL/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.

Delete a comment

DELETE /issues/{issue_id}/comments/{comment_id} Example request:

curl -X DELETE "$ATLAS_URL/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:

curl "$ATLAS_URL/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:

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

Overview

Resources

Endpoints

Create an issue

List issues

Get an issue

Update an issue

Delete an issue

Get metrics

List comments

Add a comment

Update a comment

Delete a comment

List issue files

Overview

Resources

Documentation Index

​Endpoints

​Create an issue

​List issues

​Get an issue

​Update an issue

​Delete an issue

​Get metrics

​List comments

​Add a comment

​Update a comment

​Delete a comment

​List issue files

Endpoints

Create an issue

List issues

Get an issue

Update an issue

Delete an issue

Get metrics

List comments

Add a comment

Update a comment

Delete a comment

List issue files