A bug represents a problem found during use or testing that causes the product to behave incorrectly. Bugs typically include a summary of the issue, steps to reproduce it, and the expected versus actual behavior.

Bug attributes

The table below lists the fields available on bugs, including those you can specify when creating or updating a bug, as well as fields returned in API responses.

The Usage column shows which endpoints accept values for that field. If the Usage column is blank, the field is read-only—it's returned in responses but can't be manually specified or updated in any request.

Field	Type	Description	Usage
`title`	string	The title of the bug.	POST, PATCH
`handle`	string	A unique identifier for the bug, shown in the Atono application as the item ID (e.g., `BUG-123`).
`content`	array of content chunks	A description of the bug, including a summary, reproduction steps, and expected and actual behavior. Each chunk must include a `type` and `value`. Supports `DISPLAY_HTML` (HTML-formatted content) or `TEXT` (plain text).	POST, PATCH
`position`	integer	The bug’s vertical order within its current workflow step, where `0` is the topmost item. Position is relative to the step and team backlog.
`cycleTimeMode`	string	Indicates whether the bug is marked as an `OUTLIER` (excluded) or remains `NORMAL` (included) in average cycle time calculations, reports, and staleness indicators.
`stalenessIndicatorSnoozeUntil`	datetime (ISO 8601)	The date and time until which the staleness indicator is hidden for this bug in its current step and team backlog. Once the date passes, the indicator is shown again if the bug is still stale.
`createdAt`	datetime (ISO 8601)	The date and time the bug was created.
`updatedAt`	datetime (ISO 8601)	The date and time the bug was last updated.
`doneAt`	datetime (ISO 8601)	The date and time when the bug was completed.
`deleted`	boolean	Whether the bug has been deleted.

Bug relationships

Bugs can be assigned to a user or team, associated with a workflow step, and linked to a creator (reporter). You can specify some of these relationships when creating or updating a bug.

When requesting a bug, only the type and id of each related resource are returned by default. To include full details in the response, use the ?include= query parameter.

Field	Type	Description
`assignee`	user	The user assigned to the bug. Use `?include=ASSIGNEE` to retrieve full details.
`team`	team	The team backlog the bug is assigned to. Use `?include=TEAM` to retrieve full details.
workflowStep	workflow_step	The workflow step the bug is currently assigned to. Use `?include=WORKFLOW_STEP` to retrieve full details.
`creator`*	user	The user who reported the bug. Use `?include=CREATOR` to retrieve full details.

*The creator relationship is returned in the reporter field of the response.

Creating a bug

When creating a bug, you can specify the assignee, team, and workflowStep in the relationships object. The reporter is automatically set to the user making the request and cannot be manually assigned at creation.

Updating a bug

When updating a bug, you can modify the assignee, team, workflowStep, or reporter by including them in the relationships object. To change the reporting user, use the reporter field.

The user who originally created the bug—as well as any changes to the reporter—is recorded in the Activities list in the Atono web app.

Bug relationship objects

The examples below show how to structure the relationship objects when creating or updating a bug. You can reference existing resources (like users, teams, and workflow steps) when creating or updating a bug.

assignee
Reference an existing user by id. To find valid user ids, use the Get users endpoint.

"assignee": {
  "data": {
    "type": "user",
    "id": "fe4641d7-c72a-4165-904d-89b2ded40916"
  }
}

team
Reference an existing team by id. To find valid team ids, use the Get teams endpoint.

"team": {
  "data": {
    "type": "team",
    "id": "0cd0c8b8-734f-4c17-a07c-e993b04af480"
  }
}

To unassign a user or remove a bug from a team's backlog, set the value to null:

"assignee": { "data": null },
"team": { "data": null }

workflowStep
Reference an existing workflow step by id. To find valid ids, use the Get workflow steps endpoint.

"workflowStep": {
  "data": {
    "type": "workflow_step",
    "id": "014806ef-a67c-4835-b80c-e75683044c07"
  }
}

reporter
To update the user who reported the bug, include the reporter field in a PATCH request. The id must reference an existing user.

"reporter": {
  "data": {
    "type": "user",
    "id": "2edaca9f-b07e-4af1-b425-1f0b6bf69c0a"
  }
}

Example: Get a bug

This example shows a GET response for a single bug, including its attributes, relationships, and any related resources in the included array.

{
  "data": {
    "type": "bug",
    "id": "f239bdd6-9016-4922-a229-b4120aadba15",
    "attributes": {
      "title": "MIDI input not detected after changing external controllers (Error code: MIDI-202)",
      "handle": "BUG-4",
      "position": 0,
      "content": [
        {
          "type": "DISPLAY_HTML",
          "value": "<h3>Summary</h3><p>When switching between two external MIDI controllers in the Virtual Vintage Synth app, the MIDI input is not detected by the app, and an error code \"MIDI-202\" is shown, requiring a restart to resolve the issue.</p><h3>Reproduction Steps</h3><ol><li><p>Open the Virtual Vintage Synth app.</p></li><li><p>Connect external MIDI controller A and verify it works by playing notes.</p></li><li><p>Disconnect MIDI controller A and connect external MIDI controller B.</p></li><li><p>Try to play notes using MIDI controller B.</p></li></ol><h3>Expected Behavior</h3><p>The app should recognize and accept input from MIDI controller B without requiring a restart.</p><h3>Actual Behavior</h3><p>The app does not detect any MIDI input from controller B and displays the error code \"MIDI-202.\" A restart is necessary for the app to register the new controller.</p>"
        }
      ],
      "cycleTimeMode": "NORMAL",
      "createdAt": "2024-09-04T22:28:31Z",
      "updatedAt": "2025-06-24T03:37:37Z",
      "deleted": false
    },
    "relationships": {
      "assignee": {
        "links": {
          "related": "/api/v1/users/fe4641d7-c72a-4165-904d-89b2ded40916"
        },
        "data": {
          "type": "user",
          "id": "fe4641d7-c72a-4165-904d-89b2ded40916"
        }
      },
      "team": {
        "links": {
          "related": "/api/v1/teams/0cd0c8b8-734f-4c17-a07c-e993b04af480"
        },
        "data": {
          "type": "team",
          "id": "0cd0c8b8-734f-4c17-a07c-e993b04af480"
        }
      },
      "workflowStep": {
        "links": {
          "related": "/api/v1/workflow-steps/014806ef-a67c-4835-b80c-e75683044c07"
        },
        "data": {
          "type": "workflow_step",
          "id": "014806ef-a67c-4835-b80c-e75683044c07"
        }
      },
      "reporter": {
        "links": {
          "related": "/api/v1/users/2edaca9f-b07e-4af1-b425-1f0b6bf69c0a"
        },
        "data": {
          "type": "user",
          "id": "2edaca9f-b07e-4af1-b425-1f0b6bf69c0a"
        }
      }
    }
  },
  "included": [
    {
      "type": "workflow_step",
      "id": "014806ef-a67c-4835-b80c-e75683044c07",
      "attributes": {
        "name": "Review",
        "category": "IN_PROGRESS",
        "position": 2,
        "color": "966bec",
        "stepType": "REVIEW",
        "forStory": true,
        "forBug": true,
        "allowNewItems": true
      }
    },
    {
      "type": "team",
      "id": "0cd0c8b8-734f-4c17-a07c-e993b04af480",
      "attributes": {
        "name": "Synth Support Squad",
        "description": "Engineering team responsible for maintaining, optimizing, and enhancing our virtual synthesizer. They ensure smooth operation and implement new features while providing top-notch user support.",
        "createdAt": "2024-07-18T22:49:52Z",
        "updatedAt": "2025-02-07T05:52:49Z",
        "isPublic": true,
        "backlogManagementByOwners": false
      },
      "relationships": {
        "members": {
          "links": {
            "self": "/api/v1/teams/0cd0c8b8-734f-4c17-a07c-e993b04af480/relationships/members"
          },
          "data": [
            {
              "type": "user",
              "id": "2edaca9f-b07e-4af1-b425-1f0b6bf69c0a"
            },
            {
              "type": "user",
              "id": "bf60edfc-be09-4fea-8597-33c5b333ce05"
            },
            {
              "type": "user",
              "id": "fe4641d7-c72a-4165-904d-89b2ded40916"
            },
            {
              "type": "user",
              "id": "a0215837-3d34-4e0b-9796-2ec4d8aa9573"
            }
          ],
          "meta": {
            "count": 4
          }
        }
      }
    },
    {
      "type": "user",
      "id": "fe4641d7-c72a-4165-904d-89b2ded40916",
      "attributes": {
        "createdAt": "2024-08-10T00:45:55Z",
        "updatedAt": "2024-08-10T00:46:58Z",
        "invitedAt": "2025-01-23T22:58:21Z",
        "email": "oliver.resonance@virtualvintage.com",
        "fullName": "Oliver Resonance",
        "deleted": false
      }
    },
    {
      "type": "user",
      "id": "2edaca9f-b07e-4af1-b425-1f0b6bf69c0a",
      "attributes": {
        "createdAt": "2024-08-10T00:45:56Z",
        "updatedAt": "2025-06-10T23:34:40Z",
        "invitedAt": "2025-01-23T22:58:21Z",
        "email": "ella.rhythm@virtualvintage.com",
        "fullName": "Ella Rhythm",
        "deleted": false
      }
    }
  ]
}

Example: Create a bug

This example shows a POST request for creating a new bug, including a formatted content section and relationships such as team, assignee, and workflow step. The id values for user, team, and workflow step must reference existing resources in your workspace. You can retrieve them using the Get users, Get teams, and Get workflow steps endpoints.

{
  "data": {
    "type": "bug",
    "attributes": {
      "title": "Dropdown menus open off-screen on smaller displays",
      "content": [
        {
          "type": "DISPLAY_HTML",
          "value": "<h1>Summary</h1><p>On smaller laptops or tablets, dropdown menus in the preset editor open partially off-screen, making certain options inaccessible without zooming out or scrolling the entire page.</p><h1>Reproduction Steps</h1><ol><li>Open Virtual Vintage on a 13\" display or in split-screen mode</li><li>Navigate to the preset editor</li><li>Click on any dropdown (e.g., waveform type, modulation source)</li><li>Observe that the dropdown list opens beyond the visible screen area</li></ol><h1>Expected Behavior</h1><p>Dropdown menus should open within the visible viewport, using smart positioning to avoid clipping.</p><h1>Actual Behavior</h1><p>Menus extend off-screen, making lower options difficult or impossible to select.</p><h1>UX insight</h1><p><strong>UX insight:</strong> Designers may suggest switching to a modal selector or implementing auto-positioning logic. If not addressed, this creates friction in core workflows and may frustrate users on common devices.</p>"
        }
      ]
    },
    "relationships": {
      "assignee": {
        "data": {
          "type": "user",
          "id": "d73f1297-825d-4f9a-9529-51ab0f8b0cfe"
        }
      },
      "team": {
        "data": {
          "type": "team",
          "id": "0cd0c8b8-734f-4c17-a07c-e993b04af480"
        }
      },
      "workflowStep": {
        "data": {
          "type": "workflow_step",
          "id": "014806ef-a67c-4835-b80c-e75683044c07"
        }
      }
    }
  }
}