API reference

Issue tracking

Search, create, edit, transition, rank, link, comment on and log work on issues.

`GET /v1/orgs/:orgId/issues`

Searches with the query language (jql), paged. Default order: most recently updated.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`jql`	`string`	No	`""`	up to 10,000 characters
`startAt`	`integer`	No	`0`	0–100000; coerced from a string
`maxResults`	`integer`	No	`50`	1–1000; coerced from a string
`order`	`"rank" \| "updated" \| "created" \| "key"`	No

Response 200

{
  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
  }[]
  total: number
  startAt: number
  maxResults: number
  scanned: number
}

`POST /v1/orgs/:orgId/issues/search`

The same search with the query in the body (long queries).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Default	Notes
`jql`	`string`	No	`""`	up to 10,000 characters
`startAt`	`integer`	No	`0`	0–100000; coerced from a string
`maxResults`	`integer`	No	`50`	1–1000; coerced from a string
`order`	`"rank" \| "updated" \| "created" \| "key"`	No

Response 200

{
  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
  }[]
  total: number
  startAt: number
  maxResults: number
  scanned: number
}

`GET /v1/orgs/:orgId/issues/export`

Issues matching a query as a CSV (Jira-style columns) or JSON download, up to 10,000.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`jql`	`string`	No	`""`	up to 10,000 characters
`format`	`"csv" \| "json"`	No	`"csv"`

Response 200 with no body.

`POST /v1/orgs/:orgId/issues/import`

Imports a Jira CSV export (or this API's JSON export) into a space, 200 rows per call: pass startRow and keyMap from the previous answer until done. Space admins only.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body (up to 5 MB)

Field	Type	Required	Notes
`space`	`string`	Yes	1–64 characters
`format`	`"csv" \| "json"`	Yes
`content`	`string`	Yes	1–5,242,880 characters
`startRow`	`integer`	No	≥ 0
`keyMap`	`object`	No	keys up to 64 characters; values: string (up to 64 characters)
`createMissing`	`boolean`	No

Response 200

{
  total: number
  processed: number
  done: boolean
  nextRow: null | number
  keyMap: {
    [key: string]: string
  }
  results: {
    row: number
    key?: string
    from?: string
    error?: string
    warnings?: string[]
  }[]
}

Errors

Status	Message
`413`	Import files can be up to 5 MB.

`GET /v1/orgs/:orgId/issues/labels`

Labels in use (most used first), for suggestions; space narrows to one 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

{
  labels: string[]
}

`POST /v1/orgs/:orgId/issues`

Creates an issue. Catalog fields take names or ids, people take ids or emails, parent an issue key.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`type`	`string`	No	up to 80 characters
`summary`	`string`	No	up to 255 characters
`description`	`string`	No	up to 65,536 characters
`priority`	`string`	No	up to 80 characters; can be `null`
`assignee`	`string`	No	up to 320 characters; can be `null`
`reporter`	`string`	No	up to 320 characters; can be `null`
`labels`	`string[]`	No	up to 30 items; each up to 64 characters
`components`	`string[]`	No	up to 50 items; each up to 100 characters
`fixVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`affectsVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`dueDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`storyPoints`	`number`	No	0–10000; can be `null`
`originalEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`remainingEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`environment`	`string`	No	up to 32,768 characters; can be `null`
`parent`	`string`	No	up to 64 characters; can be `null`
`sprint`	`string`	No	up to 100 characters; can be `null`
`securityLevel`	`string`	No	up to 80 characters; can be `null`
`resolution`	`string`	No	up to 80 characters; can be `null`
`fields`	`object`	No	keys up to 100 characters; values: any JSON
`requestType`	`string`	No	up to 80 characters
`participants`	`string[]`	No	up to 100 items; each up to 320 characters
`space`	`string`	Yes	1–64 characters
`summary`	`string`	Yes	1–255 characters; trimmed

Response 201

{
  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
  }
}

`POST /v1/orgs/:orgId/issues/rank`

Reorders issues: puts them (in order) right 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
`before`	`string`	No	up to 64 characters
`after`	`string`	No	up to 64 characters

Response 200

{
  issues: {
    issueId: string
    key: string
    rank: string
  }[]
}

`POST /v1/orgs/:orgId/issues/bulk`

Runs one operation (edit, transition, move, delete, watch, unwatch) on up to 200 issues; each reports its own result.

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
`operation`	`"edit" \| "transition" \| "move" \| "delete" \| "watch" \| "unwatch"`	Yes
`fields`	`object`	No
`fields.type`	`string`	No	up to 80 characters
`fields.summary`	`string`	No	up to 255 characters
`fields.description`	`string`	No	up to 65,536 characters
`fields.priority`	`string`	No	up to 80 characters; can be `null`
`fields.assignee`	`string`	No	up to 320 characters; can be `null`
`fields.reporter`	`string`	No	up to 320 characters; can be `null`
`fields.labels`	`string[]`	No	up to 30 items; each up to 64 characters
`fields.components`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.fixVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.affectsVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.dueDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`fields.startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`fields.storyPoints`	`number`	No	0–10000; can be `null`
`fields.originalEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`fields.remainingEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`fields.environment`	`string`	No	up to 32,768 characters; can be `null`
`fields.parent`	`string`	No	up to 64 characters; can be `null`
`fields.sprint`	`string`	No	up to 100 characters; can be `null`
`fields.securityLevel`	`string`	No	up to 80 characters; can be `null`
`fields.resolution`	`string`	No	up to 80 characters; can be `null`
`fields.fields`	`object`	No	keys up to 100 characters; values: any JSON
`fields.requestType`	`string`	No	up to 80 characters
`fields.participants`	`string[]`	No	up to 100 items; each up to 320 characters
`transition`	`string`	No	up to 80 characters
`space`	`string`	No	up to 64 characters
`type`	`string`	No	up to 80 characters

Response 200

{
  results: {
    issue: string
    ok: true
    error?: undefined
  } | {
    issue: string
    ok: false
    error: string
  }[]
  done: number
  failed: number
}

`GET /v1/orgs/:orgId/issues/:issueKey`

Everything the issue page shows: fields, description, comments, links, attachments, children, transitions.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Query parameter	Type	Required	Notes
`remember`	`"0" \| "1"`	No

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
  }
  space: {
    spaceId: string
    key: string
    name: string
    template: "basic" | "service" | "scrum" | "kanban" | "bugs"
    icon?: string
    color?: string
    leadId?: string
    archived: boolean
  }
  description: string
  comments: {
    commentId: string
    issueId: string
    body: string
    authorId: string
    authorType: string
    visibility: "public" | "internal"
    mentions: string[]
    reactions: {
      [key: string]: string[]
    }
    editedAt?: number
    createdAt: number
    updatedAt: number
  }[]
  links: {
    issue: {
      issueId: string
      key: string
      summary: string
      typeId: string
      statusId: string
      statusCategory: "done" | "todo" | "inprogress"
      priorityId?: string
      assigneeId?: string
    }
    linkId: string
    typeId: string
    direction: "outward" | "inward"
    label: string
  }[]
  remoteLinks: {
    linkId: string
    kind: "deployment" | "branch" | "commit" | "pull" | "page" | "web"
    url?: string
    title: string
    ref?: string
    meta: {
      [key: string]: unknown
    }
    createdBy?: string
    createdAt: number
    updatedAt: number
  }[]
  attachments: {
    attachmentId: string
    name: string
    size: number
    contentType: string
    uploadedBy: string
    createdAt: number
  }[]
  children: {
    issueId: string
    key: string
    summary: string
    typeId: string
    statusId: string
    statusCategory: "done" | "todo" | "inprogress"
    priorityId?: string
    assigneeId?: string
  }[]
  parent?: {
    issueId: string
    key: string
    summary: string
    typeId: string
    statusId: string
    statusCategory: "done" | "todo" | "inprogress"
    priorityId?: string
    assigneeId?: string
  }
  worklogs: {
    worklogId: string
    issueId: string
    spaceId: string
    authorId: string
    started: number
    seconds: number
    comment: string
    createdAt: number
    updatedAt: number
  }[]
  transitions: {
    id: string
    name: string
    to: string
    toName: string
    toCategory: string
    fields: string[]
    blocked?: string
  }[]
  workflow: {
    workflowId: string
    name: string
  }
  sla: {
    elapsed: number
    remaining?: number
    breached: boolean
    running: boolean
    paused: boolean
    stopped: boolean
    breachAt?: number
    id: string
    name: string
    goalMinutes?: number
    calendar: "business" | "always"
  }[]
  permissions: {
    edit: boolean
    delete: boolean
    link?: boolean
    worklog?: boolean
    comment?: boolean
    create?: boolean
    browse?: boolean
    editOwn?: boolean
    transition?: boolean
    assign?: boolean
    assignable?: boolean
    deleteOwn?: boolean
    editComments?: boolean
    deleteComments?: boolean
    attach?: boolean
    deleteAttachments?: boolean
    manageWatchers?: boolean
    manageSprints?: boolean
    move?: boolean
    administer?: boolean
    serviceAgent?: boolean
  }
}

`PATCH /v1/orgs/:orgId/issues/:issueKey`

Edits fields (status changes go through transitions).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`type`	`string`	No	up to 80 characters
`summary`	`string`	No	up to 255 characters
`description`	`string`	No	up to 65,536 characters
`priority`	`string`	No	up to 80 characters; can be `null`
`assignee`	`string`	No	up to 320 characters; can be `null`
`reporter`	`string`	No	up to 320 characters; can be `null`
`labels`	`string[]`	No	up to 30 items; each up to 64 characters
`components`	`string[]`	No	up to 50 items; each up to 100 characters
`fixVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`affectsVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`dueDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`storyPoints`	`number`	No	0–10000; can be `null`
`originalEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`remainingEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`environment`	`string`	No	up to 32,768 characters; can be `null`
`parent`	`string`	No	up to 64 characters; can be `null`
`sprint`	`string`	No	up to 100 characters; can be `null`
`securityLevel`	`string`	No	up to 80 characters; can be `null`
`resolution`	`string`	No	up to 80 characters; can be `null`
`fields`	`object`	No	keys up to 100 characters; values: any JSON
`requestType`	`string`	No	up to 80 characters
`participants`	`string[]`	No	up to 100 items; each up to 320 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
  }
  changes: {
    field: string
    from?: unknown
    to?: unknown
    fromText?: string
    toText?: string
  }[]
}

`DELETE /v1/orgs/:orgId/issues/:issueKey`

Deletes an issue with its comments, attachments, work logs and subtasks.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  issueId: string
  key: string
  subtasks: number
}

`GET /v1/orgs/:orgId/issues/:issueKey/transitions`

Transitions available from the issue's status, with the reason when a condition blocks one.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  transitions: {
    id: string
    name: string
    to: string
    toName: string
    toCategory: string
    fields: string[]
    blocked?: string
  }[]
  workflow: {
    workflowId: string
    name: 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
    }
  }
}

`POST /v1/orgs/:orgId/issues/:issueKey/transitions`

Moves the issue through its workflow (by transition id or name, or the target status name).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`transition`	`string`	Yes	1–80 characters
`fields`	`object`	No
`fields.type`	`string`	No	up to 80 characters
`fields.summary`	`string`	No	up to 255 characters
`fields.description`	`string`	No	up to 65,536 characters
`fields.priority`	`string`	No	up to 80 characters; can be `null`
`fields.assignee`	`string`	No	up to 320 characters; can be `null`
`fields.reporter`	`string`	No	up to 320 characters; can be `null`
`fields.labels`	`string[]`	No	up to 30 items; each up to 64 characters
`fields.components`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.fixVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.affectsVersions`	`string[]`	No	up to 50 items; each up to 100 characters
`fields.dueDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`fields.startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`fields.storyPoints`	`number`	No	0–10000; can be `null`
`fields.originalEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`fields.remainingEstimate`	`number \| string`	No	0–315360000; up to 40 characters; can be `null`
`fields.environment`	`string`	No	up to 32,768 characters; can be `null`
`fields.parent`	`string`	No	up to 64 characters; can be `null`
`fields.sprint`	`string`	No	up to 100 characters; can be `null`
`fields.securityLevel`	`string`	No	up to 80 characters; can be `null`
`fields.resolution`	`string`	No	up to 80 characters; can be `null`
`fields.fields`	`object`	No	keys up to 100 characters; values: any JSON
`fields.requestType`	`string`	No	up to 80 characters
`fields.participants`	`string[]`	No	up to 100 items; each up to 320 characters
`comment`	`string`	No	up to 32,768 characters
`commentVisibility`	`"public" \| "internal"`	No

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
  }
  changes: {
    field: string
    from?: unknown
    to?: unknown
    fromText?: string
    toText?: string
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/move`

Moves the issue (and its subtasks) to another space under a new key; the old key keeps working.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`space`	`string`	Yes	1–64 characters
`type`	`string`	No	up to 80 characters
`status`	`string`	No	up to 80 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
  }
  from: string
  subtasks: number
}

`POST /v1/orgs/:orgId/issues/:issueKey/clone`

Copies an issue (optionally with subtasks and links) and links the copy to the original.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`summary`	`string`	No	1–255 characters; trimmed
`subtasks`	`boolean`	No
`links`	`boolean`	No

Response 201

{
  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/:issueKey/children`

Child issues (subtasks, or stories of an epic).

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  issues: {
    issueId: string
    key: string
    summary: string
    typeId: string
    statusId: string
    statusCategory: "done" | "todo" | "inprogress"
    priorityId?: string
    assigneeId?: string
  }[]
}

`GET /v1/orgs/:orgId/issues/:issueKey/history`

Field changes, newest first.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  history: {
    changeId: string
    actorId: string
    actorType: string
    at: number
    items: {
      field: string
      from?: unknown
      to?: unknown
      fromText?: string
      toText?: string
    }[]
  }[]
}

`GET /v1/orgs/:orgId/issues/:issueKey/comments`

Comments, oldest first (order=desc for newest first). Internal comments only for agents.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Query parameter	Type	Required	Notes
`order`	`"asc" \| "desc"`	No

Response 200

{
  comments: {
    commentId: string
    issueId: string
    body: string
    authorId: string
    authorType: string
    visibility: "public" | "internal"
    mentions: string[]
    reactions: {
      [key: string]: string[]
    }
    editedAt?: number
    createdAt: number
    updatedAt: number
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/comments`

Adds a comment (Markdown; mention people as @[Name](user:usr_…)). Internal comments are for service desk agents.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`body`	`string`	Yes	1–32,768 characters
`visibility`	`"public" \| "internal"`	No

Response 201

{
  comment: {
    commentId: string
    issueId: string
    body: string
    authorId: string
    authorType: string
    visibility: "public" | "internal"
    mentions: string[]
    reactions: {
      [key: string]: string[]
    }
    editedAt?: number
    createdAt: number
    updatedAt: number
  }
}

`PATCH /v1/orgs/:orgId/issues/:issueKey/comments/:commentId`

Edits a comment (the previous body is kept as a revision) or changes its visibility.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:commentId`	Comment id (`icm_…`).

Request body

Field	Type	Required	Notes
`body`	`string`	No	1–32,768 characters
`visibility`	`"public" \| "internal"`	No

Response 200

{
  comment: {
    commentId: string
    issueId: string
    body: string
    authorId: string
    authorType: string
    visibility: "public" | "internal"
    mentions: string[]
    reactions: {
      [key: string]: string[]
    }
    editedAt?: number
    createdAt: number
    updatedAt: number
  }
}

`DELETE /v1/orgs/:orgId/issues/:issueKey/comments/:commentId`

Deletes a comment.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:commentId`	Comment id (`icm_…`).

Response 200

{
  commentId: string
}

`GET /v1/orgs/:orgId/issues/:issueKey/comments/:commentId/revisions`

Earlier versions of an edited comment.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:commentId`	Comment id (`icm_…`).

Response 200

{
  revisions: {
    body: string
    at: number
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/comments/:commentId/reactions`

Toggles the caller's reaction.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:commentId`	Comment id (`icm_…`).

Request body

Field	Type	Required	Notes
`emoji`	`string`	Yes	1–16 characters

Response 200

{
  reactions: {
    [key: string]: string[]
  }
}

`GET /v1/orgs/:orgId/issues/:issueKey/links`

Issue links and remote links (web pages, Knowledge pages, branches, commits, pull requests, deployments).

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  links: {
    issue: {
      issueId: string
      key: string
      summary: string
      typeId: string
      statusId: string
      statusCategory: "done" | "todo" | "inprogress"
      priorityId?: string
      assigneeId?: string
    }
    linkId: string
    typeId: string
    direction: "outward" | "inward"
    label: string
  }[]
  remoteLinks: {
    linkId: string
    kind: "deployment" | "branch" | "commit" | "pull" | "page" | "web"
    url?: string
    title: string
    ref?: string
    meta: {
      [key: string]: unknown
    }
    createdBy?: string
    createdAt: number
    updatedAt: number
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/links`

Links to another issue by link type (id, name, or either direction's wording, e.g. "is blocked by").

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`type`	`string`	Yes	1–80 characters
`issue`	`string`	Yes	1–64 characters
`inward`	`boolean`	No

Response 201

{
  linkId: string
  typeId: string
  source: string
  target: string
}

`DELETE /v1/orgs/:orgId/issues/:issueKey/links/:linkId`

Removes a link from both issues.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:linkId`	Link id (`ilk_…` for issue links, `irl_…` for remote links).

Response 200

{
  linkId: string
}

`POST /v1/orgs/:orgId/issues/:issueKey/remote-links`

Links a web page or Knowledge page.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`url`	`string`	Yes	up to 2,000 characters; URL
`title`	`string`	No	up to 200 characters
`kind`	`"web" \| "page"`	No

Response 201

{
  linkId: string
}

`DELETE /v1/orgs/:orgId/issues/:issueKey/remote-links/:linkId`

Removes a remote link.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:linkId`	Link id (`ilk_…` for issue links, `irl_…` for remote links).

Response 200

{
  linkId: string
}

`GET /v1/orgs/:orgId/issues/:issueKey/attachments`

Attachments.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  attachments: {
    attachmentId: string
    name: string
    size: number
    contentType: string
    uploadedBy: string
    createdAt: number
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/attachments`

Starts an upload: returns a presigned PUT (15 minutes, size and type signed). Finish with /complete.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	Yes	1–255 characters
`size`	`integer`	Yes	≥ 1
`contentType`	`string`	No	up to 200 characters

Response 201

{
  attachmentId: string
  uploadUrl: string
  headers: {
    "content-type": string
  }
}

`POST /v1/orgs/:orgId/issues/:issueKey/attachments/:attachmentId/complete`

Finishes an upload once the file is in place.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:attachmentId`	Attachment id (`att_…`).

Response 200

{
  attachmentId: string
}

`GET /v1/orgs/:orgId/issues/:issueKey/attachments/:attachmentId`

A 5-minute download link (inline=1 opens images, PDFs and plain text in the browser).

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:attachmentId`	Attachment id (`att_…`).

Query parameter	Type	Required	Notes
`inline`	`"0" \| "1"`	No

Response 200

{
  url: string
  name: string
  contentType: string
  size: number
}

`DELETE /v1/orgs/:orgId/issues/:issueKey/attachments/:attachmentId`

Deletes an attachment and its file.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:attachmentId`	Attachment id (`att_…`).

Response 200

{
  attachmentId: string
}

`GET /v1/orgs/:orgId/issues/:issueKey/worklogs`

Work logs.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Response 200

{
  worklogs: {
    worklogId: string
    issueId: string
    spaceId: string
    authorId: string
    started: number
    seconds: number
    comment: string
    createdAt: number
    updatedAt: number
  }[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/worklogs`

Logs work ("1h 30m" or seconds); the remaining estimate goes down unless told otherwise.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`timeSpent`	`integer \| string`	Yes	60–604800; 1–40 characters
`started`	`integer`	No
`comment`	`string`	No	up to 4,000 characters
`remaining`	`object \| object \| object`	No

Response 201

{
  worklogId: string
  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
  }
}

`PATCH /v1/orgs/:orgId/issues/:issueKey/worklogs/:worklogId`

Changes a work log.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:worklogId`	Work log id (`wlg_…`).

Request body

Field	Type	Required	Notes
`timeSpent`	`integer \| string`	No	60–604800; 1–40 characters
`started`	`integer`	No
`comment`	`string`	No	up to 4,000 characters

Response 200

{
  worklogId: string
}

`DELETE /v1/orgs/:orgId/issues/:issueKey/worklogs/:worklogId`

Deletes a work log (its time goes back on the remaining estimate).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).
`:worklogId`	Work log id (`wlg_…`).

Response 200

{
  worklogId: string
}

`POST /v1/orgs/:orgId/issues/:issueKey/watchers`

Starts or stops watching (the caller, or someone else with manage watchers).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`watching`	`boolean`	Yes
`userId`	`string`	No	up to 64 characters

Response 200

{
  watchers: string[]
}

`POST /v1/orgs/:orgId/issues/:issueKey/votes`

Votes for an issue, or withdraws the vote.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:issueKey`	Issue key (`WEB-12`; former keys of moved issues and renamed spaces work too) or issue id (`iss_…`).

Request body

Field	Type	Required	Notes
`voting`	`boolean`	Yes

Response 200

{
  voters: string[]
}

Issue tracking

On this page