Words we use
These docs use a few words that mean something particular in By Dawn. Here they are in plain terms, with a link to where each one is explained in full.
By Dawn and its board
Section titled “By Dawn and its board”By Dawn
Section titled “By Dawn”The product these docs are about, and its public name. The app itself still says SAW in a few places until it is
renamed: its window and menu, some buttons and messages, the saw command line, saw-agent, ticket ids such as
SAW-123, and the sawrun.com addresses. They are the same product. Where a page quotes the app, it quotes it
exactly, SAW included.
Organization
Section titled “Organization”Your company or team in By Dawn. Everything belongs to one, and every API path starts with
/orgs/{orgId}. See How By Dawn is organised.
Project
Section titled “Project”One board of work, with its own columns and its own ticket prefix (SAW in SAW-123).
Status (column)
Section titled “Status (column)”A column on a project’s board. The API calls columns statuses, so a ticket’s statusId says which
column it’s in. See Board and columns.
A tag By Dawn puts on the few columns its workflow depends on: backlog, todo, building, review
and completed. Teams rename columns, but the role stays, so look columns up by role. See Projects
and their boards.
Ticket
Section titled “Ticket”One piece of work on a board. It sits in exactly one column. See Tickets and sub-tickets.
id and identifier
Section titled “id and identifier”A ticket’s two names. The id (ticket-…) is for your code and every API path. The identifier
(SAW-123) is for people.
Sub-ticket
Section titled “Sub-ticket”A ticket with a parent (parentTicketId), used to break work down. It shows as SAW-123.1. See Break work
into sub-tickets.
A project’s time-boxed iteration, like a sprint. See Cycles.
Epic and milestone
Section titled “Epic and milestone”An epic groups the tickets of one deliverable, such as a feature. A milestone is an optional phase of one epic, with its own target date. See Epics and milestones.
Estimate
Section titled “Estimate”A ticket’s size in points, on the project’s scale. Cycles add estimates up to measure velocity and capacity. See Estimates.
Release
Section titled “Release”The tickets that ship together, with their notes. Shipping a release adds it to the project’s changelog. See Releases and the project changelog.
Agent run
Section titled “Agent run”By Dawn’s AI agent working on a ticket. Moving a ticket into the building column starts one, which is
why an API key isn’t allowed to make that move.
Missions
Section titled “Missions”Mission
Section titled “Mission”The list of steps a ticket goes through while By Dawn’s agent works on it, such as a plan a person approves, tests that pass and By Dawn merging the pull request. A team can turn missions off. See Missions and templates.
Mission step
Section titled “Mission step”One item in a mission. By Dawn checks some steps itself, a person decides others, and By Dawn carries out
a few on its own after the agent finishes. A ticket held at a step names it in heldAt.
A stage of a mission, such as Plan, Build or Ship. Steps run phase by phase, in order.
Mission template
Section titled “Mission template”A named list of ticked steps, written by a person, that a ticket’s mission starts from. Each mode (planning or build) can have one default template, and a project’s default beats the organization’s. See Templates and defaults.
Preset
Section titled “Preset”A ready-made way to tick a mission’s steps: Auto, Quick, Standard or Thorough. Unlike a template, By Dawn works out a preset’s ticks for each ticket. See Choose the steps.
Checkpoint
Section titled “Checkpoint”A mission step that waits for a person, such as approving a plan or picking a mockup. The agent stops until someone answers. See Checkpoints and debriefs.
Debrief
Section titled “Debrief”What a finished mission leaves on its ticket: the steps it ran, the decisions people made and the proof for each step. See The debrief.
Agents and their setup
Section titled “Agents and their setup”Worker
Section titled “Worker”The app’s name for By Dawn’s agent while it works on a ticket. See Start a ticket.
Run config
Section titled “Run config”The machine, runtime, model and effort a ticket’s agent runs with. A ticket follows its project’s run defaults unless someone changes it. See Models and runtimes.
Remote agent
Section titled “Remote agent”A machine paired with your organization that runs By Dawn’s agent and picks up tickets. See Remote agents and machines.
One Claude sign-in on a machine. Each machine has a default seat and can hold more, each signed in to another Claude account. See Claude accounts, sign-in and seats.
Library
Section titled “Library”The organization’s skills, subagents, slash commands and shared tools, which every agent picks up when it starts. A project can switch items off for itself. See Skills & Tools.
Persona
Section titled “Persona”A stakeholder the organization describes once, such as a compliance lead, who critiques an agent’s plan in character. See Personas.
Secret
Section titled “Secret”A named value, such as an API key, that agents read as an environment variable. It’s encrypted for your own machines, so nobody can view it once it’s saved. See Secrets.
Routine
Section titled “Routine”Work an agent runs on a timetable, each run as a new ticket. See Routines.
Code and review
Section titled “Code and review”A git repository a project’s tickets work in, on GitHub, Azure DevOps or another host. A project can have many, and a ticket can work in several. See Repos.
Worktree
Section titled “Worktree”A ticket’s own checkout of one repo, on the machine running its agent, on the ticket’s branch. Every ticket gets one per repo, so agents never touch each other’s files. See Worktrees.
Pull request
Section titled “Pull request”The way a ticket’s code reaches a repo: one per repo the ticket changes, opened from the ticket’s branch. By Dawn opens it as a draft and watches its checks and reviews. See Pull requests.
Line comment
Section titled “Line comment”A comment on particular lines of a ticket’s diff, sent to its agent, posted on its pull request, or both. See Comment on a line.
Test run
Section titled “Test run”One set of test results By Dawn read from the reports a test runner wrote: a worker’s Tests and build pass step, a CI pipeline run (all its jobs and shards together), or an uploaded file. It’s tied to a commit, and through its branch to a pull request and ticket. By Dawn never runs the tests itself. See Test results. A run people work through by hand is a manual run.
Test case
Section titled “Test case”One thing to test, in a project’s case library: a title, preconditions and steps with what to expect, or an automated test in a repo, which By Dawn adds by itself. Every edit is a revision. See Test cases.
Manual run
Section titled “Manual run”A set of test cases people work through by hand against one build, recording each step’s result. By Dawn records what they did, and files a bug from a failure in one step. See Run tests by hand.
Exploratory session
Section titled “Exploratory session”One person exploring a charter without a script, within a timebox, logging notes, issues and screenshots as they go. See Exploratory sessions.
Test plan
Section titled “Test plan”The testing that signs off one release or one cycle: suites launched on your own CI or machines, and cases people run by hand, each an item of the plan. By Dawn drafts it from the cases linked to the work, the regression suites and what failed last time, and you edit it. See Plan testing for a release or cycle.
Regression suite
Section titled “Regression suite”A suite marked Regression suite, so By Dawn drafts it into every release’s and cycle’s test plan. See Mark your regression suites.
Test gate
Section titled “Test gate”A project setting, off by default, that keeps a release from shipping until its test plan passes or a person signs off what’s keeping it from passing. Ship anyway doesn’t get past it. See The test gate.
Flaky test
Section titled “Flaky test”A test that passed and failed on the same commit, or failed and then passed on a retry. By Dawn files one Flaky: ticket for it, and can re-run CI instead of waking the worker when only known-flaky tests failed. See Flaky tests.
Insights
Section titled “Insights”One Insights dashboard, looking at your work from one angle: Overview, Flow, Agents, People, Cost or Questions. See Insights.
Cycle time
Section titled “Cycle time”How long a ticket took from starting work to its first review. Insights gives the median, never the average. See Lenses and metrics.
Import and sync
Section titled “Import and sync”Connection
Section titled “Connection”One import from another tracker, such as Jira or Trello, into one project. It holds the app grant, what to bring, the mapping and, for a sync, the end date. See Import and sync.
App grant
Section titled “App grant”The approval an org admin gives on a tracker’s consent screen for By Dawn’s app to read and write there. It’s how every tracker connects, so there’s no token to paste. By Dawn keeps the grant for one connection, and gives it up when the connection ends. See Before you start.
Sync window
Section titled “Sync window”The period, up to 180 days, during which an imported project and its tracker keep each other up to date. When it ends, the tickets stay and stop updating. See Ending a sync.
Field owner
Section titled “Field owner”The side, By Dawn or the tracker, whose value wins when a synced field was changed on both sides at once. The value that lost shows on the ticket as a sync conflict. See When both sides change the same field.
Chat integrations
Section titled “Chat integrations”Chat connection
Section titled “Chat connection”One Slack workspace, Discord server or Microsoft 365 tenant that an org admin added to By Dawn. Disconnecting it deletes everything By Dawn kept for it. See Chat integrations.
Channel binding
Section titled “Channel binding”A chat channel tied to one project by a project admin. It says where the channel’s requests go, who may file them and which updates post there. See Bind a channel.
Linked chat account
Section titled “Linked chat account”A member’s chat identity, tied to their By Dawn account, with the scopes they chose. A button they click in chat then acts as them. See Connect your chat account.
Request
Section titled “Request”A ticket filed from chat by someone who isn’t acting as a linked member, such as a guest or someone from another organisation. It records their chat name and id, and never makes them a member. See Who files what.
Administration
Section titled “Administration”Owner, admin and member
Section titled “Owner, admin and member”The three roles someone can have in an organization. Admins manage people and most settings, and owners also decide how people sign in. See Roles.
A named group of people in an organization who own work together. A ticket can have one owning team, its teamId,
and a team works in the projects it’s attached to. A team can also be given access to a project or a Docs space.
See Teams, and Organize work by team for the API.
Restricted project
Section titled “Restricted project”A project only its own members, and the organization’s owners and admins, can open. Other projects are open to everyone in the organization. See Open or restricted.
Identity provider (IdP)
Section titled “Identity provider (IdP)”The service that holds your company’s accounts and checks passwords, such as Okta, Microsoft Entra ID or Google Workspace. See Single sign-on.
Verified domain
Section titled “Verified domain”An email domain, such as acme.com, that your organization has proved it owns with a DNS record. Single sign-on
and SCIM only reach people at one. See Verify a domain.
SSO connection
Section titled “SSO connection”The link between your organization and your identity provider, over OIDC or SAML, that lets people sign in through it. See Add a connection.
The standard way an identity provider adds and removes an app’s users for you. See SCIM provisioning.
Keys and tokens
Section titled “Keys and tokens”API key
Section titled “API key”A long-lived secret (saw_live_…) that an owner or admin creates in Settings › Organization › Security
(API keys). It belongs to one organization and lives on your server. See
Authentication.
Access token
Section titled “Access token”A short-lived token (about 15 minutes) your code gets by exchanging the key, and sends with every
request as Authorization: Bearer ….
What a key may do: read only (tickets:read), read and write (tickets:write as well), or only send test results
(tests:write). See Scopes.
Responses
Section titled “Responses”Envelope
Section titled “Envelope”The shape every response has: { "ok": true, "data": … } when it worked, or { "ok": false, "error": "<slug>" } when it didn’t. See Responses and errors.
The short, fixed error code in error, such as ticket_not_found. Write your error handling
against it.
Cursor
Section titled “Cursor”A bookmark for the next page of a list (nextCursor). Pass it back as it is. See
Pagination.
Correlation ID
Section titled “Correlation ID”The X-Correlation-Id header on every response. Quote it if you ask us about a call.
On this site
Section titled “On this site”Recipe
Section titled “Recipe”A complete program, in one file, that does one job with the API, written in TypeScript, Python, Java, C#, Go and cURL. Our CI runs every one of them against the live API. See How the recipes are written.
Try it
Section titled “Try it”The console and the Run buttons that call the API from this site with your own key. See Try it in your browser.