AI bug workflow

An AI coding agent can read bug reports from a board, fix them in your codebase, and move each card as it progresses. The agent uses an API key from an account that can read and move cards on that board.

Find the board and columns

  1. Call GET /api/v1/boards and pick the organization and board the agent should work on.
  2. Call GET /api/v1/boards/:boardId. The response includes lists, which are the board's columns or categories, and labels, which are its tags.
  3. Note the IDs you need:
    • The source list, such as your backlog or ideas column.
    • The label that marks a bug, such as Bug, if your board uses one.
    • The destination lists, such as Testing, Fixed, or Done, based on your workflow.

Read the bug cards

Call GET /api/v1/cards with the board, list, and label you noted. For example, ?boardId=<board-id>&listId=<source-list-id>&labelId=<bug-label-id>. Leave out labelId if the source column holds only bugs. Leave out listId to find Bug-labeled cards across the whole board.

Follow nextCursor until it is null. Each card includes its full title, its Markdown description, its priority, its labels, and its current listId. See Read cards for the query parameters and responses.

Fix, verify, and move

For each card:

  1. Call GET /api/v1/cards/:cardId to read the current report. Keep the listId from the response, because you need it for a guarded move.

  2. Reproduce the issue, make the fix in the right repository, and run your checks.

  3. Call PATCH /api/v1/cards/:cardId with the destination and the source list you observed:

    { "listId": "<destination-list-id>", "expectedListId": "<observed-source-list-id>" }

    Use the Testing column while validation is still pending. Use a completion column such as Fixed, Done, or Finished once the fix meets your team's definition of done.

  4. Check the listId in the response. If you get 409 conflict, or the network request fails before you see a response, read the card again before you decide to retry. See Move a card.

Limits and permissions

Every request acts as the key owner. Revoked or expired keys fail authentication. Moves also check the owner's current organization role, so a role that cannot move cards gets 403.

The API allows 60 requests per minute per key. Keep the agent under that limit, and back off when you receive 429.