API reference
Issue configuration
Statuses, issue types, priorities, resolutions, link types, workflows, custom fields, screens and permission schemes.
See Issues.
GET /v1/orgs/:orgId/issues/config/meta
Everything the Issues app loads once: catalogs, fields, spaces, people, templates.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
settings: {
statuses: {
id: string
name: string
category: "done" | "todo" | "inprogress"
description?: string
}[]
issueTypes: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
level: number
description?: string
}[]
priorities: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
}[]
defaultPriorityId: string
resolutions: {
id: string
name: string
description?: string
}[]
linkTypes: {
id: string
name: string
outward: string
inward: string
}[]
}
settingsVersion: number
fields: {
fieldId: string
name: string
type: "number" | "text" | "url" | "date" | "user" | "team" | "labels" | "select" | "checkbox" | "paragraph" | "datetime" | "multiselect" | "cascading" | "users"
description?: string
options?: {
id: string
name: string
disabled?: boolean
children?: {
id: string
name: string
}[]
}[]
spaceIds?: string[]
typeIds?: string[]
defaultValue?: unknown
}[]
systemFields: [{
id: "summary"
name: "Summary"
type: "text"
}, {
id: "description"
name: "Description"
type: "paragraph"
}, {
id: "type"
name: "Type"
type: "issuetype"
}, {
id: "status"
name: "Status"
type: "status"
}, {
id: "priority"
name: "Priority"
type: "priority"
}, {
id: "resolution"
name: "Resolution"
type: "resolution"
}, {
id: "assignee"
name: "Assignee"
type: "user"
}, {
id: "reporter"
name: "Reporter"
type: "user"
}, {
id: "labels"
name: "Labels"
type: "labels"
}, {
id: "components"
name: "Components"
type: "components"
}, {
id: "fixVersions"
name: "Fix versions"
type: "versions"
}, {
id: "affectsVersions"
name: "Affects versions"
type: "versions"
}, {
id: "dueDate"
name: "Due date"
type: "date"
}, {
id: "startDate"
name: "Start date"
type: "date"
}, {
id: "storyPoints"
name: "Story points"
type: "number"
}, {
id: "originalEstimate"
name: "Original estimate"
type: "duration"
}, {
id: "remainingEstimate"
name: "Remaining estimate"
type: "duration"
}, {
id: "environment"
name: "Environment"
type: "paragraph"
}, {
id: "parent"
name: "Parent"
type: "issue"
}, {
id: "sprint"
name: "Sprint"
type: "sprint"
}, {
id: "securityLevel"
name: "Security level"
type: "security"
}]
spaces: {
access?: {
spaceId: string
admin: boolean
create: boolean
}
orgId: string
spaceId: string
key: string
name: string
description: string
template: "basic" | "service" | "scrum" | "kanban" | "bugs"
leadId?: string
icon?: string
color?: string
archived: boolean
archivedAt?: number
seq: number
config: {
issueTypeIds: string[]
defaultTypeId: string
workflows: {
[key: string]: string
}
screens: {
create: {
[key: string]: string
}
edit: {
[key: string]: string
}
view: {
[key: string]: string
}
}
fieldSettings: {
[key: string]: {
required?: boolean
hidden?: boolean
description?: string
}
}
customFieldIds: string[]
access: {
visibility: "org" | "private"
members: {
type: "user" | "team"
id: string
role: "admin" | "viewer" | "member"
}[]
}
permissionSchemeId?: string
securityLevels: {
id: string
name: string
description?: string
grants: object[]
}[]
defaultSecurityLevelId?: string
notifications: {
created?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
deleted?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
assigned?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
updated?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
transitioned?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
commented?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
mentioned?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
resolved?: ("participants" | "assignee" | "reporter" | "lead" | "watchers")[]
}
defaultAssignee: "lead" | "unassigned"
estimation: "count" | "storyPoints" | "originalEstimate"
boardId?: string
servicedesk?: {
requestTypes: {
id: string
name: string
description?: string
icon?: string
typeId: string
group?: string
fields: object
hidden?: boolean
}[]
queues: {
id: string
name: string
query: string
columns?: object
}[]
slas: {
id: string
name: string
start: object
pause: object
stop: object
goals: object
}[]
hours: {
timeZone: string
days: {
[key: number]: object
}
holidays: string[]
}
portal: {
enabled: boolean
title: string
intro: string
access: "any" | "org" | "listed"
customers: string[]
}
cannedResponses: {
id: string
name: string
body: string
}[]
satisfaction: boolean
}
formerKeys?: string[]
}
version: number
createdAt: number
updatedAt: number
}[]
people: {
userId: string
email?: string
name?: string
role: string
teams: string[]
}[]
teams: {
teamId: string
slug: string
name: string
members: string[]
}[]
workflows: {
workflowId: string
name: string
description?: string
}[]
screens: {
screenId: string
name: string
tabs: {
name: string
fields: string[]
}[]
}[]
schemes: {
schemeId: string
name: string
description?: string
}[]
templates: {
name: string
description: string
id: "basic" | "service" | "scrum" | "kanban" | "bugs"
}[]
actor: {
id: string
type: "user" | "key" | "system" | "automation"
scopes: string[]
}
}GET /v1/orgs/:orgId/issues/config/settings
The org's catalogs and their version (for optimistic updates).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
settings: {
statuses: {
id: string
name: string
category: "done" | "todo" | "inprogress"
description?: string
}[]
issueTypes: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
level: number
description?: string
}[]
priorities: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
}[]
defaultPriorityId: string
resolutions: {
id: string
name: string
description?: string
}[]
linkTypes: {
id: string
name: string
outward: string
inward: string
}[]
}
version: number
}PUT /v1/orgs/:orgId/issues/config/settings
Replaces the catalogs. Statuses and types still used by workflows or spaces can't be removed.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
settings | object | Yes | |
settings.statuses | object[] | Yes | up to 200 items |
settings.statuses[].id | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.statuses[].name | string | Yes | 1–80 characters; trimmed |
settings.statuses[].category | "todo" | "inprogress" | "done" | Yes | |
settings.statuses[].description | string | No | up to 500 characters |
settings.issueTypes | object[] | Yes | up to 50 items |
settings.issueTypes[].id | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.issueTypes[].name | string | Yes | 1–80 characters; trimmed |
settings.issueTypes[].icon | string | Yes | up to 40 characters |
settings.issueTypes[].color | "gray" | "blue" | "green" | "teal" | "yellow" | "orange" | "red" | "pink" | "purple" | Yes | |
settings.issueTypes[].level | integer | Yes | -1–5 |
settings.issueTypes[].description | string | No | up to 500 characters |
settings.priorities | object[] | Yes | up to 20 items |
settings.priorities[].id | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.priorities[].name | string | Yes | 1–80 characters; trimmed |
settings.priorities[].icon | string | Yes | up to 40 characters |
settings.priorities[].color | "gray" | "blue" | "green" | "teal" | "yellow" | "orange" | "red" | "pink" | "purple" | Yes | |
settings.defaultPriorityId | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.resolutions | object[] | Yes | up to 50 items |
settings.resolutions[].id | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.resolutions[].name | string | Yes | 1–80 characters; trimmed |
settings.resolutions[].description | string | No | up to 500 characters |
settings.linkTypes | object[] | Yes | up to 50 items |
settings.linkTypes[].id | string | Yes | matches ^[a-z0-9_]{1,32}$ |
settings.linkTypes[].name | string | Yes | 1–80 characters; trimmed |
settings.linkTypes[].outward | string | Yes | 1–60 characters; trimmed |
settings.linkTypes[].inward | string | Yes | 1–60 characters; trimmed |
baseVersion | integer | Yes | ≥ 0 |
Response 200
{
settings: {
statuses: {
id: string
name: string
category: "done" | "todo" | "inprogress"
description?: string
}[]
issueTypes: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
level: number
description?: string
}[]
priorities: {
id: string
name: string
icon: string
color: "gray" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | "teal"
}[]
defaultPriorityId: string
resolutions: {
id: string
name: string
description?: string
}[]
linkTypes: {
id: string
name: string
outward: string
inward: string
}[]
}
version: number
}GET /v1/orgs/:orgId/issues/config/workflows
Every workflow with its statuses and transitions.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
workflows: {
workflowId: string
name: string
description?: string
definition: {
initialStatusId: string
statuses: {
statusId: string
x?: number
y?: number
}[]
transitions: {
id: string
name: string
from: string[]
to: string
fields?: string[]
conditions?: object[]
validators?: object[]
postFunctions?: object[]
}[]
autoResolution?: boolean
}
version: number
updatedAt?: number
}[]
}GET /v1/orgs/:orgId/issues/config/workflows/:workflowId
A workflow and the spaces that use it.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:workflowId | Workflow id (wfl_…, or a built-in one such as wf_software). |
Response 200
{
workflow: {
workflowId: string
name: string
description?: string
definition: {
initialStatusId: string
statuses: {
statusId: string
x?: number
y?: number
}[]
transitions: {
id: string
name: string
from: string[]
to: string
fields?: string[]
conditions?: {
type: "orgRole"
roles: object
} | {
type: "spaceRole"
roles: object
} | {
type: "assignee"
} | {
type: "reporter"
} | {
type: "permission"
permission: "link" | "worklog" | "delete" | "comment" | "create" | "browse" | "edit" | "editOwn" | "transition" | "assign" | "assignable" | "deleteOwn" | "editComments" | "deleteComments" | "attach" | "deleteAttachments" | "manageWatchers" | "manageSprints" | "move" | "administer" | "serviceAgent"
} | {
type: "fieldSet"
field: string
} | {
type: "subtasksDone"
}[]
validators?: {
type: "required"
fields: object
message?: string
} | {
type: "query"
query: string
message: string
}[]
postFunctions?: {
type: "assign"
to: "reporter" | "lead" | "unassigned" | "currentUser"
} | {
type: "setResolution"
resolutionId: null | string
} | {
type: "setField"
field: string
value: unknown
} | {
type: "clearField"
field: string
} | {
type: "comment"
body: string
}[]
}[]
autoResolution?: boolean
}
version: number
updatedAt?: number
}
spaces: {
spaceId: string
key: string
name: string
}[]
}POST /v1/orgs/:orgId/issues/config/workflows
Creates a workflow (every status must be reachable from the initial one).
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
description | string | No | up to 500 characters |
baseVersion | integer | No | ≥ 0 |
definition | object | Yes | |
definition.initialStatusId | string | Yes | up to 32 characters |
definition.statuses | object[] | Yes | 1–100 items |
definition.statuses[].statusId | string | Yes | up to 32 characters |
definition.statuses[].x | number | No | |
definition.statuses[].y | number | No | |
definition.transitions | object[] | Yes | up to 200 items |
definition.transitions[].id | string | Yes | up to 40 characters |
definition.transitions[].name | string | Yes | up to 60 characters |
definition.transitions[].from | string[] | Yes | up to 100 items; each up to 32 characters |
definition.transitions[].to | string | Yes | up to 32 characters |
definition.transitions[].fields | string[] | No | up to 30 items; each up to 64 characters |
definition.transitions[].conditions | (object | object | object | object | object | object | object)[] | No | up to 10 items |
definition.transitions[].validators | (object | object)[] | No | up to 10 items |
definition.transitions[].postFunctions | (object | object | object | object | object)[] | No | up to 10 items |
definition.autoResolution | boolean | No |
Response 201
{
workflow: {
workflowId: string
name: string
description?: string
definition: {
initialStatusId: string
statuses: {
statusId: string
x?: number
y?: number
}[]
transitions: {
id: string
name: string
from: string[]
to: string
fields?: string[]
conditions?: {
type: "orgRole"
roles: object
} | {
type: "spaceRole"
roles: object
} | {
type: "assignee"
} | {
type: "reporter"
} | {
type: "permission"
permission: "link" | "worklog" | "delete" | "comment" | "create" | "browse" | "edit" | "editOwn" | "transition" | "assign" | "assignable" | "deleteOwn" | "editComments" | "deleteComments" | "attach" | "deleteAttachments" | "manageWatchers" | "manageSprints" | "move" | "administer" | "serviceAgent"
} | {
type: "fieldSet"
field: string
} | {
type: "subtasksDone"
}[]
validators?: {
type: "required"
fields: object
message?: string
} | {
type: "query"
query: string
message: string
}[]
postFunctions?: {
type: "assign"
to: "reporter" | "lead" | "unassigned" | "currentUser"
} | {
type: "setResolution"
resolutionId: null | string
} | {
type: "setField"
field: string
value: unknown
} | {
type: "clearField"
field: string
} | {
type: "comment"
body: string
}[]
}[]
autoResolution?: boolean
}
version: number
updatedAt?: number
}
}PUT /v1/orgs/:orgId/issues/config/workflows/:workflowId
Replaces a workflow; pass baseVersion to fail instead of overwriting newer edits.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:workflowId | Workflow id (wfl_…, or a built-in one such as wf_software). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
description | string | No | up to 500 characters |
baseVersion | integer | No | ≥ 0 |
definition | object | Yes | |
definition.initialStatusId | string | Yes | up to 32 characters |
definition.statuses | object[] | Yes | 1–100 items |
definition.statuses[].statusId | string | Yes | up to 32 characters |
definition.statuses[].x | number | No | |
definition.statuses[].y | number | No | |
definition.transitions | object[] | Yes | up to 200 items |
definition.transitions[].id | string | Yes | up to 40 characters |
definition.transitions[].name | string | Yes | up to 60 characters |
definition.transitions[].from | string[] | Yes | up to 100 items; each up to 32 characters |
definition.transitions[].to | string | Yes | up to 32 characters |
definition.transitions[].fields | string[] | No | up to 30 items; each up to 64 characters |
definition.transitions[].conditions | (object | object | object | object | object | object | object)[] | No | up to 10 items |
definition.transitions[].validators | (object | object)[] | No | up to 10 items |
definition.transitions[].postFunctions | (object | object | object | object | object)[] | No | up to 10 items |
definition.autoResolution | boolean | No |
Response 200
{
workflow: {
workflowId: string
name: string
description?: string
definition: {
initialStatusId: string
statuses: {
statusId: string
x?: number
y?: number
}[]
transitions: {
id: string
name: string
from: string[]
to: string
fields?: string[]
conditions?: {
type: "orgRole"
roles: object
} | {
type: "spaceRole"
roles: object
} | {
type: "assignee"
} | {
type: "reporter"
} | {
type: "permission"
permission: "link" | "worklog" | "delete" | "comment" | "create" | "browse" | "edit" | "editOwn" | "transition" | "assign" | "assignable" | "deleteOwn" | "editComments" | "deleteComments" | "attach" | "deleteAttachments" | "manageWatchers" | "manageSprints" | "move" | "administer" | "serviceAgent"
} | {
type: "fieldSet"
field: string
} | {
type: "subtasksDone"
}[]
validators?: {
type: "required"
fields: object
message?: string
} | {
type: "query"
query: string
message: string
}[]
postFunctions?: {
type: "assign"
to: "reporter" | "lead" | "unassigned" | "currentUser"
} | {
type: "setResolution"
resolutionId: null | string
} | {
type: "setField"
field: string
value: unknown
} | {
type: "clearField"
field: string
} | {
type: "comment"
body: string
}[]
}[]
autoResolution?: boolean
}
version: number
updatedAt?: number
}
}DELETE /v1/orgs/:orgId/issues/config/workflows/:workflowId
Deletes a workflow no space uses.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:workflowId | Workflow id (wfl_…, or a built-in one such as wf_software). |
Response 200
{
workflowId: string
}GET /v1/orgs/:orgId/issues/config/fields
Custom fields and the built-in fields.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
fields: {
fieldId: string
name: string
type: "number" | "text" | "url" | "date" | "user" | "team" | "labels" | "select" | "checkbox" | "paragraph" | "datetime" | "multiselect" | "cascading" | "users"
description?: string
options?: {
id: string
name: string
disabled?: boolean
children?: {
id: string
name: string
}[]
}[]
spaceIds?: string[]
typeIds?: string[]
defaultValue?: unknown
}[]
systemFields: [{
id: "summary"
name: "Summary"
type: "text"
}, {
id: "description"
name: "Description"
type: "paragraph"
}, {
id: "type"
name: "Type"
type: "issuetype"
}, {
id: "status"
name: "Status"
type: "status"
}, {
id: "priority"
name: "Priority"
type: "priority"
}, {
id: "resolution"
name: "Resolution"
type: "resolution"
}, {
id: "assignee"
name: "Assignee"
type: "user"
}, {
id: "reporter"
name: "Reporter"
type: "user"
}, {
id: "labels"
name: "Labels"
type: "labels"
}, {
id: "components"
name: "Components"
type: "components"
}, {
id: "fixVersions"
name: "Fix versions"
type: "versions"
}, {
id: "affectsVersions"
name: "Affects versions"
type: "versions"
}, {
id: "dueDate"
name: "Due date"
type: "date"
}, {
id: "startDate"
name: "Start date"
type: "date"
}, {
id: "storyPoints"
name: "Story points"
type: "number"
}, {
id: "originalEstimate"
name: "Original estimate"
type: "duration"
}, {
id: "remainingEstimate"
name: "Remaining estimate"
type: "duration"
}, {
id: "environment"
name: "Environment"
type: "paragraph"
}, {
id: "parent"
name: "Parent"
type: "issue"
}, {
id: "sprint"
name: "Sprint"
type: "sprint"
}, {
id: "securityLevel"
name: "Security level"
type: "security"
}]
}POST /v1/orgs/:orgId/issues/config/fields
Creates a custom field (text, number, date, select, multi-select, cascading, people, team, URL, checkbox, labels).
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed | |
type | "text" | "paragraph" | "number" | "date" | "datetime" | "select" | "multiselect" | "cascading" | "user" | "users" | "team" | "url" | "checkbox" | "labels" | Yes | ||
description | string | No | up to 500 characters | |
options | object[] | No | up to 1,000 items | |
options[].id | string | No | "" | up to 40 characters |
options[].name | string | Yes | 1–100 characters; trimmed | |
options[].disabled | boolean | No | ||
options[].children | object[] | No | up to 200 items | |
options[].children[].id | string | No | "" | up to 40 characters |
options[].children[].name | string | Yes | 1–100 characters; trimmed | |
spaceIds | string[] | No | up to 1,000 items; each up to 64 characters | |
typeIds | string[] | No | up to 50 items; each up to 32 characters | |
defaultValue | any JSON | No |
Response 201
{
field: {
fieldId: string
name: string
type: "number" | "text" | "url" | "date" | "user" | "team" | "labels" | "select" | "checkbox" | "paragraph" | "datetime" | "multiselect" | "cascading" | "users"
description?: string
options?: {
id: string
name: string
disabled?: boolean
children?: {
id: string
name: string
}[]
}[]
spaceIds?: string[]
typeIds?: string[]
defaultValue?: unknown
}
}PUT /v1/orgs/:orgId/issues/config/fields/:fieldId
Changes a custom field (its type can't change).
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:fieldId | Custom field id (cf_…). |
Request body
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed | |
type | "text" | "paragraph" | "number" | "date" | "datetime" | "select" | "multiselect" | "cascading" | "user" | "users" | "team" | "url" | "checkbox" | "labels" | Yes | ||
description | string | No | up to 500 characters | |
options | object[] | No | up to 1,000 items | |
options[].id | string | No | "" | up to 40 characters |
options[].name | string | Yes | 1–100 characters; trimmed | |
options[].disabled | boolean | No | ||
options[].children | object[] | No | up to 200 items | |
options[].children[].id | string | No | "" | up to 40 characters |
options[].children[].name | string | Yes | 1–100 characters; trimmed | |
spaceIds | string[] | No | up to 1,000 items; each up to 64 characters | |
typeIds | string[] | No | up to 50 items; each up to 32 characters | |
defaultValue | any JSON | No |
Response 200
{
field: {
fieldId: string
name: string
type: "number" | "text" | "url" | "date" | "user" | "team" | "labels" | "select" | "checkbox" | "paragraph" | "datetime" | "multiselect" | "cascading" | "users"
description?: string
options?: {
id: string
name: string
disabled?: boolean
children?: {
id: string
name: string
}[]
}[]
spaceIds?: string[]
typeIds?: string[]
defaultValue?: unknown
}
}DELETE /v1/orgs/:orgId/issues/config/fields/:fieldId
Deletes the definition; values stay on issues but are no longer shown or searchable.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:fieldId | Custom field id (cf_…). |
Response 200
{
fieldId: string
}GET /v1/orgs/:orgId/issues/config/screens
Screens: which fields show on create, edit and view, in tabs.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
screens: {
screenId: string
name: string
tabs: {
name: string
fields: string[]
}[]
}[]
}POST /v1/orgs/:orgId/issues/config/screens
Creates a screen.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
tabs | object[] | Yes | 1–10 items |
tabs[].name | string | Yes | up to 40 characters |
tabs[].fields | string[] | Yes | up to 100 items; each up to 64 characters |
Response 201
{
screen: {
screenId: string
name: string
tabs: {
name: string
fields: string[]
}[]
}
}PUT /v1/orgs/:orgId/issues/config/screens/:screenId
Replaces a screen.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:screenId | Screen id (scr_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
tabs | object[] | Yes | 1–10 items |
tabs[].name | string | Yes | up to 40 characters |
tabs[].fields | string[] | Yes | up to 100 items; each up to 64 characters |
Response 200
{
screen: {
screenId: string
name: string
tabs: {
name: string
fields: string[]
}[]
}
}DELETE /v1/orgs/:orgId/issues/config/screens/:screenId
Deletes a screen no space uses.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:screenId | Screen id (scr_…). |
Response 200
{
screenId: string
}GET /v1/orgs/:orgId/issues/config/schemes
Permission schemes and the permissions they can grant.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
schemes: {
schemeId: string
name: string
description?: string
grants: {
link?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
worklog?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
delete?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
comment?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
create?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
browse?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
edit?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
transition?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assign?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assignable?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
attach?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteAttachments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageWatchers?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageSprints?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
move?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
administer?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
serviceAgent?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
}
}[]
permissions: ["browse", "create", "edit", "editOwn", "transition", "assign", "assignable", "delete", "deleteOwn", "comment", "editComments", "deleteComments", "attach", "deleteAttachments", "link", "worklog", "manageWatchers", "manageSprints", "move", "administer", "serviceAgent"]
}POST /v1/orgs/:orgId/issues/config/schemes
Creates a permission scheme.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
description | string | No | up to 500 characters |
grants | object | Yes | values: (object | object | object | object | object | object | object | object)[] (up to 50 items) |
Response 201
{
scheme: {
schemeId: string
name: string
description?: string
grants: {
link?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
worklog?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
delete?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
comment?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
create?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
browse?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
edit?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
transition?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assign?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assignable?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
attach?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteAttachments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageWatchers?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageSprints?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
move?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
administer?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
serviceAgent?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
}
}
}PUT /v1/orgs/:orgId/issues/config/schemes/:schemeId
Replaces a permission scheme's grants.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:schemeId | Permission scheme id (psc_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–80 characters; trimmed |
description | string | No | up to 500 characters |
grants | object | Yes | values: (object | object | object | object | object | object | object | object)[] (up to 50 items) |
Response 200
{
scheme: {
schemeId: string
name: string
description?: string
grants: {
link?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
worklog?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
delete?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
comment?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
create?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
browse?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
edit?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
transition?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assign?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
assignable?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteOwn?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
editComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteComments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
attach?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
deleteAttachments?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageWatchers?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
manageSprints?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
move?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
administer?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
serviceAgent?: {
type: "spaceRole"
role: "admin" | "viewer" | "member"
} | {
type: "orgRole"
role: string
} | {
type: "user"
id: string
} | {
type: "team"
id: string
} | {
type: "reporter"
} | {
type: "assignee"
} | {
type: "lead"
} | {
type: "anyone"
}[]
}
}
}DELETE /v1/orgs/:orgId/issues/config/schemes/:schemeId
Deletes a permission scheme no space uses.
Auth: user access token or platform agent key · Scope: issues:admin
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:schemeId | Permission scheme id (psc_…). |
Response 200
{
schemeId: string
}