API reference
Boards and sprints
Boards, backlogs, sprint planning, sprint reports and velocity.
See Issues.
GET /v1/orgs/:orgId/issues/boards
Boards the caller can see (space narrows to boards showing that space).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
space | string | No | up to 64 characters |
Response 200
{
boards: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}[]
}POST /v1/orgs/:orgId/issues/boards
Creates a board over one or more spaces, with columns from their workflows' statuses.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
type | "scrum" | "kanban" | Yes | |
spaces | string[] | Yes | 1–20 items; each up to 64 characters |
query | string | No | up to 2,000 characters |
Response 201
{
board: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}
}GET /v1/orgs/:orgId/issues/boards/:boardId
A board's configuration.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
Response 200
{
board: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}
}PATCH /v1/orgs/:orgId/issues/boards/:boardId
Changes a board's name, columns (status mapping, WIP limits), swimlanes, quick filters, card fields and sharing.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | 1–80 characters; trimmed |
config | object | No | |
config.spaceIds | string[] | No | 1–20 items; each up to 64 characters |
config.query | string | No | up to 2,000 characters |
config.columns | object[] | No | 1–20 items |
config.columns[].id | string | Yes | up to 40 characters |
config.columns[].name | string | Yes | 1–60 characters; trimmed |
config.columns[].statusIds | string[] | Yes | up to 50 items; each up to 32 characters |
config.columns[].min | integer | No | 0–999 |
config.columns[].max | integer | No | 0–999 |
config.swimlanes | "none" | "assignee" | "epic" | "parent" | "priority" | "query" | No | |
config.swimlaneQueries | object[] | No | up to 20 items |
config.swimlaneQueries[].id | string | Yes | up to 40 characters |
config.swimlaneQueries[].name | string | Yes | 1–60 characters; trimmed |
config.swimlaneQueries[].query | string | Yes | up to 2,000 characters |
config.quickFilters | object[] | No | up to 30 items |
config.quickFilters[].id | string | Yes | up to 40 characters |
config.quickFilters[].name | string | Yes | 1–60 characters; trimmed |
config.quickFilters[].query | string | Yes | up to 2,000 characters |
config.cardFields | string[] | No | up to 6 items; each up to 64 characters |
config.estimation | "storyPoints" | "originalEstimate" | "count" | No | |
config.hideDoneAfterDays | integer | No | 0–365 |
config.kanbanBacklog | boolean | No | |
config.wipExcludesSubtasks | boolean | No | |
config.sharing | object | No | |
config.sharing.org | boolean | Yes | |
config.sharing.teams | string[] | Yes | up to 50 items; each up to 64 characters |
config.sharing.users | string[] | Yes | up to 200 items; each up to 64 characters |
baseVersion | integer | No | ≥ 0 |
Response 200
{
board: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}
}DELETE /v1/orgs/:orgId/issues/boards/:boardId
Deletes a board without an active sprint; issues in its future sprints return to the backlog.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
Response 200
{
boardId: string
}GET /v1/orgs/:orgId/issues/boards/:boardId/issues
The board's cards: the active sprints' issues (scrum) or the flow (kanban), with quick filters (comma-separated ids).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
quickFilters | string | No | up to 400 characters |
sprint | string | No | up to 64 characters |
Response 200
{
board: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}
issues: {
orgId: string
issueId: string
spaceId: string
number: number
key: string
typeId: string
summary: string
statusId: string
statusCategory: "done" | "todo" | "inprogress"
statusChangedAt?: number
resolutionId?: string
resolvedAt?: number
priorityId?: string
assigneeId?: string
reporterId?: string
creatorId?: string
labels: string[]
componentIds: string[]
fixVersionIds: string[]
affectsVersionIds: string[]
dueDate?: string
startDate?: string
storyPoints?: number
originalEstimate?: number
remainingEstimate?: number
timeSpent?: number
environment?: string
parentId?: string
sprintId?: string
closedSprintIds: string[]
rank: string
watchers: string[]
voters: string[]
securityLevelId?: string
fields: {
[key: string]: boolean | null | string | number | string[] | {
parent: string
child?: string
}
}
excerpt: string
statusLog: [string, number][]
commentCount: number
attachmentCount: number
requestTypeId?: string
channel?: string
participants: string[]
satisfaction?: number
satisfactionComment?: string
sla: {
[key: string]: {
runningSince?: number
elapsed: number
paused?: boolean
stopped?: boolean
goal?: number
calendar: "business" | "always"
breached?: boolean
startedAt?: number
stoppedAt?: number
}
}
version: number
createdAt: number
updatedAt: number
}[]
sprints: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}[]
lanes: {
[key: string]: string
}
parents: {
[key: string]: {
issueId: string
key: string
summary: string
typeId: string
statusId: string
parentId?: string
}
}
subtasks: {
[key: string]: {
total: number
done: number
}
}
spaces: {
spaceId: string
key: string
name: string
}[]
}GET /v1/orgs/:orgId/issues/boards/:boardId/backlog
Active and future sprints with their issues, the backlog and the epics of the board's spaces.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
quickFilters | string | No | up to 400 characters |
Response 200
{
board: {
boardId: string
name: string
ownerId?: string
config: {
type: "scrum" | "kanban"
spaceIds: string[]
query?: string
columns: {
id: string
name: string
statusIds: string[]
min?: number
max?: number
}[]
swimlanes: "query" | "none" | "assignee" | "priority" | "parent" | "epic"
swimlaneQueries?: {
id: string
name: string
query: string
}[]
quickFilters: {
id: string
name: string
query: string
}[]
cardFields: string[]
estimation: "count" | "storyPoints" | "originalEstimate"
hideDoneAfterDays?: number
kanbanBacklog?: boolean
wipExcludesSubtasks?: boolean
sharing: {
org: boolean
teams: string[]
users: string[]
}
}
version: number
createdAt: number
updatedAt: number
}
sprints: {
issueIds: string[]
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}[]
issues: {
orgId: string
issueId: string
spaceId: string
number: number
key: string
typeId: string
summary: string
statusId: string
statusCategory: "done" | "todo" | "inprogress"
statusChangedAt?: number
resolutionId?: string
resolvedAt?: number
priorityId?: string
assigneeId?: string
reporterId?: string
creatorId?: string
labels: string[]
componentIds: string[]
fixVersionIds: string[]
affectsVersionIds: string[]
dueDate?: string
startDate?: string
storyPoints?: number
originalEstimate?: number
remainingEstimate?: number
timeSpent?: number
environment?: string
parentId?: string
sprintId?: string
closedSprintIds: string[]
rank: string
watchers: string[]
voters: string[]
securityLevelId?: string
fields: {
[key: string]: boolean | null | string | number | string[] | {
parent: string
child?: string
}
}
excerpt: string
statusLog: [string, number][]
commentCount: number
attachmentCount: number
requestTypeId?: string
channel?: string
participants: string[]
satisfaction?: number
satisfactionComment?: string
sla: {
[key: string]: {
runningSince?: number
elapsed: number
paused?: boolean
stopped?: boolean
goal?: number
calendar: "business" | "always"
breached?: boolean
startedAt?: number
stoppedAt?: number
}
}
version: number
createdAt: number
updatedAt: number
}[]
backlogIds: string[]
epics: {
issueId: string
key: string
summary: string
statusCategory: "done" | "todo" | "inprogress"
progress: {
total: number
done: number
points: number
}
}[]
subtaskCounts: {
[key: string]: {
total: number
done: number
points: number
}
}
}POST /v1/orgs/:orgId/issues/boards/:boardId/move
Moves a card to a column (through the workflow) and optionally ranks it next to another card. 409 names the fields a transition asks for.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
issue | string | Yes | 1–64 characters |
columnId | string | Yes | 1–40 characters |
before | string | No | up to 64 characters |
after | string | No | up to 64 characters |
Response 200
{
issue: {
orgId: string
issueId: string
spaceId: string
number: number
key: string
typeId: string
summary: string
statusId: string
statusCategory: "done" | "todo" | "inprogress"
statusChangedAt?: number
resolutionId?: string
resolvedAt?: number
priorityId?: string
assigneeId?: string
reporterId?: string
creatorId?: string
labels: string[]
componentIds: string[]
fixVersionIds: string[]
affectsVersionIds: string[]
dueDate?: string
startDate?: string
storyPoints?: number
originalEstimate?: number
remainingEstimate?: number
timeSpent?: number
environment?: string
parentId?: string
sprintId?: string
closedSprintIds: string[]
rank: string
watchers: string[]
voters: string[]
securityLevelId?: string
fields: {
[key: string]: boolean | null | string | number | string[] | {
parent: string
child?: string
}
}
excerpt: string
statusLog: [string, number][]
commentCount: number
attachmentCount: number
requestTypeId?: string
channel?: string
participants: string[]
satisfaction?: number
satisfactionComment?: string
sla: {
[key: string]: {
runningSince?: number
elapsed: number
paused?: boolean
stopped?: boolean
goal?: number
calendar: "business" | "always"
breached?: boolean
startedAt?: number
stoppedAt?: number
}
}
version: number
createdAt: number
updatedAt: number
}
}GET /v1/orgs/:orgId/issues/boards/:boardId/velocity
Committed and completed estimates of the last closed sprints.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:boardId | Board id (brd_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
count | integer | No | 1–30; coerced from a string |
Response 200
{
board: {
boardId: string
name: string
estimation: "count" | "storyPoints" | "originalEstimate"
}
sprints: {
sprintId: string
name: string
committed: number
completed: number
}[]
average: number
}GET /v1/orgs/:orgId/issues/sprints
Sprints of the boards the caller can see: active first, then future, then closed (newest first).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
space | string | No | up to 64 characters |
board | string | No | up to 64 characters |
state | "future" | "active" | "closed" | No |
Response 200
{
sprints: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}[]
}POST /v1/orgs/:orgId/issues/sprints
Creates a future sprint on a scrum board.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
boardId | string | Yes | 1–64 characters |
name | string | No | up to 80 characters |
goal | string | No | up to 1,000 characters |
startDate | integer | No | |
endDate | integer | No |
Response 201
{
sprint: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}
}POST /v1/orgs/:orgId/issues/sprints/move
Puts issues into a sprint (sprint: null for the backlog), optionally ranked before or after another issue.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
issues | string[] | Yes | 1–200 items; each up to 64 characters |
sprint | string | Yes | up to 64 characters; can be null |
before | string | No | up to 64 characters |
after | string | No | up to 64 characters |
Response 200
{
issues: {
issueId: string
key: string
sprintId?: string
rank: string
}[]
}PATCH /v1/orgs/:orgId/issues/sprints/:sprintId
Changes a sprint's name, goal, dates, order or capacity.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:sprintId | Sprint id (spr_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | up to 80 characters |
goal | string | No | up to 1,000 characters |
startDate | integer | No | can be null |
endDate | integer | No | can be null |
position | integer | No | ≥ 0 |
capacity | number | No | 0–100000; can be null |
Response 200
{
sprint: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}
}POST /v1/orgs/:orgId/issues/sprints/:sprintId/start
Starts a future sprint; its issues become the committed scope.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:sprintId | Sprint id (spr_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | up to 80 characters |
goal | string | No | up to 1,000 characters |
startDate | integer | No | |
endDate | integer | Yes |
Response 200
{
sprint: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}
issues: number
}POST /v1/orgs/:orgId/issues/sprints/:sprintId/complete
Completes an active sprint; open issues move to moveTo (a sprint id, new or backlog).
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:sprintId | Sprint id (spr_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
moveTo | string | Yes | 1–64 characters |
Response 200
{
sprint: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}
completed: number
carried: number
movedTo: string
}GET /v1/orgs/:orgId/issues/sprints/:sprintId/report
Burndown, scope changes and outcome of a sprint.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:sprintId | Sprint id (spr_…). |
Response 200
{
sprint: {
sprintId: string
boardId: string
name: string
goal: string
state: "active" | "closed" | "future"
startDate?: number
endDate?: number
completedAt?: number
position: number
data: {
capacity?: number
report?: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
carriedTo?: string
}
}
createdAt: number
}
start: number
end: number
completedAt?: number
estimation: "count" | "storyPoints" | "originalEstimate"
burndown: {
at: number
remaining: number
scope: number
done: number
}[]
summary: {
committed: number
added: number
removed: number
completed: number
incomplete: number
completedIssueIds: string[]
incompleteIssueIds: string[]
}
committedIssueIds: string[]
issues: {
orgId: string
issueId: string
spaceId: string
number: number
key: string
typeId: string
summary: string
statusId: string
statusCategory: "done" | "todo" | "inprogress"
statusChangedAt?: number
resolutionId?: string
resolvedAt?: number
priorityId?: string
assigneeId?: string
reporterId?: string
creatorId?: string
labels: string[]
componentIds: string[]
fixVersionIds: string[]
affectsVersionIds: string[]
dueDate?: string
startDate?: string
storyPoints?: number
originalEstimate?: number
remainingEstimate?: number
timeSpent?: number
environment?: string
parentId?: string
sprintId?: string
closedSprintIds: string[]
rank: string
watchers: string[]
voters: string[]
securityLevelId?: string
fields: {
[key: string]: boolean | null | string | number | string[] | {
parent: string
child?: string
}
}
excerpt: string
statusLog: [string, number][]
commentCount: number
attachmentCount: number
requestTypeId?: string
channel?: string
participants: string[]
satisfaction?: number
satisfactionComment?: string
sla: {
[key: string]: {
runningSince?: number
elapsed: number
paused?: boolean
stopped?: boolean
goal?: number
calendar: "business" | "always"
breached?: boolean
startedAt?: number
stoppedAt?: number
}
}
version: number
createdAt: number
updatedAt: number
}[]
}DELETE /v1/orgs/:orgId/issues/sprints/:sprintId
Deletes a future sprint; its issues return to the backlog.
Auth: user access token or platform agent key · Scope: issues:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:sprintId | Sprint id (spr_…). |
Response 200
{
sprintId: string
}