Skip to content
Docs
About By Dawn Contact supportOpen By Dawn
  1. Getting started
  2. How By Dawn is organised

How By Dawn is organised

Before you write code against By Dawn, it helps to know the handful of things it’s made of. This page walks through them from the top down, and points out the details that trip people up.

In short: everything lives in one organization. Work is split into projects, and each project is a board whose columns are called statuses. A ticket always sits in exactly one column. The API is built around tickets: you read and write tickets and what’s attached to them, and you read the board around them.

This page describes them as the API sees them. For the same ideas in the app, see Board and columns, Tickets and sub-tickets, Epics and milestones and Cycles.

Organization{orgId}

Every path starts with /orgs/{orgId}. An API key belongs to one organization.

ProjectprojectId

A board. Its ticketPrefix starts every identifier (SAW-123).

StatusesstatusId

The board's columns, in order. Some carry a role.

CyclescycleId

Time-boxed iterations of this project.

TicketticketId

Sits in exactly one status. Can have a parent (sub-tickets).

CommentscommentId

Oldest first. Reactions hang off them.

RelationsrelationId

blocks, related or duplicate, to another ticket.

LabelslabelId

Shared by the organization's projects.

UsersassigneeId

Members. Not readable with an API key.

Organization

Section titled “Organization”

Your API key belongs to one organization, and every request acts on it. That’s why every path starts with /orgs/{orgId}. You can read the ID from your access token, as Authentication shows.

Projects and their boards

Section titled “Projects and their boards”

A project is one board of work, and GET /projects lists them. Each has a short prefix that starts its tickets’ names, like SAW in SAW-123. Most calls take a projectId.

Statuses are a board’s columns, in the order they’re shown. Ask for them with the project’s ID (GET /statuses?projectId=…), because a project can have its own columns. Without it you get the organization’s default board.

Teams rename and add columns, so By Dawn tags the few columns its workflow depends on with a role: backlog, todo (shown as Planning), building, review and completed. A column a team adds has no role. Roles matter to you in three places:

  • A ticket you create without choosing a column lands in the backlog one.
  • GET /tickets?open=true leaves out tickets in the completed column.
  • Moving a ticket into the building column starts By Dawn’s agent on it, which is why an API key isn’t allowed to.

Cycles are a project’s time-boxed iterations, like sprints (GET /cycles?projectId=…). A ticket’s cycleId says which one it’s planned into.

Tickets

Section titled “Tickets”

A ticket has two names, and you’ll use both:

Field Example What it’s for
id ticket-… Your code. Every API path takes it, and tickets refer to each other by it.
identifier SAW-123 People. Show it in your UI and messages. To find a ticket by it, search: GET /tickets?projectId=…&q=SAW-123 puts the exact match first.

A ticket can have a parent (parentTicketId), which makes it a sub-ticket. A sub-ticket has its own identifier, and also a displayIdentifier such as SAW-123.1 that shows its parent.

Attached to each ticket you’ll find:

  • Comments, oldest first, with emoji reactions. See Comment on a ticket.
  • Relations to other tickets: blocks, related or duplicate. To break work down, give the smaller tickets a parent instead.
  • Labels, by labelIds. Labels belong to the organization, so every project shares them.
  • A team, by teamId: the team that owns the ticket, one of the teams that work in its project. Changing it changes nothing else about the ticket. See Organize work by team.

Tickets are archived rather than deleted, so nothing disappears by accident. Archive one with POST /tickets/{ticketId}/archive, and bring it back with /unarchive.

What an API key may and may not touch is listed once, in Authentication.

Missions

Section titled “Missions”

While By Dawn’s agent works on a ticket, it follows a mission: steps such as a plan a person approves, tests that must pass and By Dawn merging the pull request. The organization keeps a library of steps and mission templates that decide which steps a new ticket starts with, and a project can tighten them for itself. Missions aren’t part of the public API yet, but a ticket that By Dawn holds at a step names it in heldAt. See Missions and templates.

A person starts the agent from the ticket (Start a ticket) and answers it when a step waits for them (Checkpoints and debriefs). The agent runs on your organization’s own machines (Remote agents and machines), with the model, skills and secrets your team sets up for it.

Do and don’t

Section titled “Do and don’t”

Do:

  • Store a ticket’s id, and show people its identifier.
  • Read a project’s columns once with GET /statuses and keep their IDs. Find a column by its role rather than its name, because teams rename columns.

Don’t:

  • Build a ticket’s ID or URL from its identifier. Search with q instead.
  • Hard-code a column name such as “Done”. Look for the completed role.