API reference

Issue spaces

Spaces, their settings, versions (releases) and components.

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

Spaces the caller can browse (archived=1 includes archived ones).

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

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

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

Response 200

{
  spaces: {
    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
  }[]
}

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

Creates a space from a template (scrum, kanban, bugs, service, basic) with its board; the caller becomes lead.

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

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

Request body

Field	Type	Required	Notes
`key`	`string`	Yes	2–10 characters; trimmed
`name`	`string`	Yes	1–80 characters; trimmed
`template`	`"scrum" \| "kanban" \| "bugs" \| "service" \| "basic"`	Yes
`description`	`string`	No	up to 2,000 characters
`leadId`	`string`	No	up to 64 characters
`icon`	`string`	No	up to 16 characters
`color`	`"gray" \| "blue" \| "green" \| "teal" \| "yellow" \| "orange" \| "red" \| "pink" \| "purple"`	No

Response 201

{
  space: {
    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: {
          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"
        }[]
      }[]
      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: string[]
          hidden?: boolean
        }[]
        queues: {
          id: string
          name: string
          query: string
          columns?: string[]
        }[]
        slas: {
          id: string
          name: string
          start: string[]
          pause: string[]
          stop: string[]
          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
  }
}

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

A space with what the caller may do in it, its versions and components.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  space: {
    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: {
          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"
        }[]
      }[]
      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: string[]
          hidden?: boolean
        }[]
        queues: {
          id: string
          name: string
          query: string
          columns?: string[]
        }[]
        slas: {
          id: string
          name: string
          start: string[]
          pause: string[]
          stop: string[]
          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
  }
  permissions: {
    link?: boolean
    worklog?: boolean
    delete?: boolean
    comment?: boolean
    create?: boolean
    browse?: boolean
    edit?: 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
  }
  allPermissions: ["browse", "create", "edit", "editOwn", "transition", "assign", "assignable", "delete", "deleteOwn", "comment", "editComments", "deleteComments", "attach", "deleteAttachments", "link", "worklog", "manageWatchers", "manageSprints", "move", "administer", "serviceAgent"]
  versions: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }[]
  components: {
    componentId: string
    spaceId: string
    name: string
    description: string
    leadId?: string
    defaultAssignee: "space" | "lead" | "unassigned"
  }[]
}

`PATCH /v1/orgs/:orgId/issues/spaces/:spaceKey`

Changes a space: name, key (old keys keep resolving), lead, and its configuration (types, workflows, screens, fields, access, security levels, notifications, service desk).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–80 characters; trimmed
`key`	`string`	No	2–10 characters; trimmed
`description`	`string`	No	up to 2,000 characters
`leadId`	`string`	No	up to 64 characters
`icon`	`string`	No	up to 16 characters
`color`	`"gray" \| "blue" \| "green" \| "teal" \| "yellow" \| "orange" \| "red" \| "pink" \| "purple"`	No
`config`	`object`	No
`config.issueTypeIds`	`string[]`	No	up to 50 items; each up to 32 characters
`config.defaultTypeId`	`string`	No	up to 32 characters
`config.workflows`	`object`	No	keys up to 32 characters; values: string (up to 64 characters)
`config.screens`	`object`	No
`config.screens.create`	`object`	Yes	values: string (up to 64 characters)
`config.screens.edit`	`object`	Yes	values: string (up to 64 characters)
`config.screens.view`	`object`	Yes	values: string (up to 64 characters)
`config.fieldSettings`	`object`	No	keys up to 64 characters; values: object
`config.customFieldIds`	`string[]`	No	up to 200 items; each up to 64 characters
`config.access`	`object`	No
`config.access.visibility`	`"org" \| "private"`	Yes
`config.access.members`	`object[]`	Yes	up to 500 items
`config.access.members[].type`	`"user" \| "team"`	Yes
`config.access.members[].id`	`string`	Yes	up to 64 characters
`config.access.members[].role`	`"admin" \| "member" \| "viewer"`	Yes
`config.permissionSchemeId`	`string`	No	up to 64 characters
`config.securityLevels`	`object[]`	No	up to 20 items
`config.securityLevels[].id`	`string`	Yes	up to 40 characters
`config.securityLevels[].name`	`string`	Yes	1–80 characters; trimmed
`config.securityLevels[].description`	`string`	No	up to 500 characters
`config.securityLevels[].grants`	`object[]`	Yes	up to 50 items
`config.securityLevels[].grants[].type`	`string`	Yes	up to 20 characters
`config.securityLevels[].grants[].role`	`string`	No	up to 20 characters
`config.securityLevels[].grants[].id`	`string`	No	up to 64 characters
`config.defaultSecurityLevelId`	`string`	No	up to 40 characters
`config.notifications`	`object`	No	values: ("assignee" \| "reporter" \| "watchers" \| "lead" \| "participants")[]
`config.defaultAssignee`	`"unassigned" \| "lead"`	No
`config.estimation`	`"storyPoints" \| "originalEstimate" \| "count"`	No
`config.servicedesk`	`object`	No
`config.servicedesk.requestTypes`	`object[]`	Yes	up to 100 items
`config.servicedesk.requestTypes[].id`	`string`	Yes	up to 40 characters
`config.servicedesk.requestTypes[].name`	`string`	Yes	1–80 characters; trimmed
`config.servicedesk.requestTypes[].description`	`string`	No	up to 500 characters
`config.servicedesk.requestTypes[].icon`	`string`	No	up to 40 characters
`config.servicedesk.requestTypes[].typeId`	`string`	Yes	up to 32 characters
`config.servicedesk.requestTypes[].group`	`string`	No	up to 60 characters
`config.servicedesk.requestTypes[].fields`	`string[]`	Yes	up to 30 items; each up to 64 characters
`config.servicedesk.requestTypes[].hidden`	`boolean`	No
`config.servicedesk.queues`	`object[]`	Yes	up to 50 items
`config.servicedesk.queues[].id`	`string`	Yes	up to 40 characters
`config.servicedesk.queues[].name`	`string`	Yes	1–80 characters; trimmed
`config.servicedesk.queues[].query`	`string`	Yes	up to 2,000 characters
`config.servicedesk.queues[].columns`	`string[]`	No	up to 20 items; each up to 64 characters
`config.servicedesk.slas`	`object[]`	Yes	up to 20 items
`config.servicedesk.slas[].id`	`string`	Yes	up to 40 characters
`config.servicedesk.slas[].name`	`string`	Yes	1–80 characters; trimmed
`config.servicedesk.slas[].start`	`string[]`	Yes	up to 20 items; each up to 80 characters
`config.servicedesk.slas[].pause`	`string[]`	Yes	up to 20 items; each up to 80 characters
`config.servicedesk.slas[].stop`	`string[]`	Yes	up to 20 items; each up to 80 characters
`config.servicedesk.slas[].goals`	`object[]`	Yes	up to 20 items
`config.servicedesk.slas[].goals[].query`	`string`	No	up to 2,000 characters
`config.servicedesk.slas[].goals[].minutes`	`integer`	Yes	1–525600
`config.servicedesk.slas[].goals[].calendar`	`"business" \| "always"`	No
`config.servicedesk.hours`	`object`	Yes
`config.servicedesk.hours.timeZone`	`string`	Yes	up to 64 characters
`config.servicedesk.hours.days`	`object`	Yes	values: integer[][] (up to 4 items, each 2 items, each 0–1440)
`config.servicedesk.hours.holidays`	`string[]`	Yes	up to 200 items; each matches `^\d{4}-\d{2}-\d{2}$`
`config.servicedesk.portal`	`object`	Yes
`config.servicedesk.portal.enabled`	`boolean`	Yes
`config.servicedesk.portal.title`	`string`	Yes	up to 100 characters
`config.servicedesk.portal.intro`	`string`	Yes	up to 2,000 characters
`config.servicedesk.portal.access`	`"org" \| "listed" \| "any"`	Yes
`config.servicedesk.portal.customers`	`string[]`	Yes	up to 5,000 items; each up to 320 characters
`config.servicedesk.cannedResponses`	`object[]`	Yes	up to 100 items
`config.servicedesk.cannedResponses[].id`	`string`	Yes	up to 40 characters
`config.servicedesk.cannedResponses[].name`	`string`	Yes	up to 80 characters
`config.servicedesk.cannedResponses[].body`	`string`	Yes	up to 8,000 characters
`config.servicedesk.satisfaction`	`boolean`	Yes
`baseVersion`	`integer`	No	≥ 0

Response 200

{
  space: {
    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: {
          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"
        }[]
      }[]
      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: string[]
          hidden?: boolean
        }[]
        queues: {
          id: string
          name: string
          query: string
          columns?: string[]
        }[]
        slas: {
          id: string
          name: string
          start: string[]
          pause: string[]
          stop: string[]
          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
  }
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/archive`

Archives a space: read-only and hidden from lists.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  space: {
    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: {
          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"
        }[]
      }[]
      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: string[]
          hidden?: boolean
        }[]
        queues: {
          id: string
          name: string
          query: string
          columns?: string[]
        }[]
        slas: {
          id: string
          name: string
          start: string[]
          pause: string[]
          stop: string[]
          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
  }
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/restore`

Restores an archived space.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  space: {
    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: {
          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"
        }[]
      }[]
      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: string[]
          hidden?: boolean
        }[]
        queues: {
          id: string
          name: string
          query: string
          columns?: string[]
        }[]
        slas: {
          id: string
          name: string
          start: string[]
          pause: string[]
          stop: string[]
          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
  }
}

`DELETE /v1/orgs/:orgId/issues/spaces/:spaceKey`

Deletes an archived space and everything in it, a batch at a time: call again while done is false.

Auth: user access token or platform agent key · Scopes: issues:write, issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  done: boolean
}

`GET /v1/orgs/:orgId/issues/spaces/:spaceKey/versions`

Versions (releases) of a space.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  versions: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }[]
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/versions`

Creates a version.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Request body

Field	Type	Required	Notes
`description`	`string`	No	up to 2,000 characters
`startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`releaseDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`archived`	`boolean`	No
`position`	`integer`	No	0–1000000
`name`	`string`	Yes	1–100 characters; trimmed

Response 201

{
  version: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }
}

`GET /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId`

A version with its issues and progress.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Response 200

{
  version: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: 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
  }[]
  counts: {
    todo: number
    inprogress: number
    done: number
    total: number
  }
  points: {
    total: number
    done: number
  }
}

`PATCH /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId`

Changes a version's name, dates, order or archived state.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`description`	`string`	No	up to 2,000 characters
`startDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`releaseDate`	`string`	No	matches `^\d{4}-\d{2}-\d{2}$`; can be `null`
`archived`	`boolean`	No
`position`	`integer`	No	0–1000000

Response 200

{
  version: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId/release`

Releases (or unreleases) a version, optionally moving unresolved issues to another version.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Request body

Field	Type	Required	Default	Notes
`released`	`boolean`	No	`true`
`moveUnresolvedTo`	`string`	No		up to 64 characters; can be `null`
`releaseDate`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`

Response 200

{
  version: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }
  moved: number
}

`GET /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId/notes`

Release notes in Markdown: resolved issues grouped by type.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Response 200

{
  markdown: string
  issues: number
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId/deployments`

Links (or unlinks) a Cloud deployment to a version.

Auth: user access token or platform agent key · Scopes: issues:write, deployments:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Request body

Field	Type	Required	Default	Notes
`deploymentId`	`string`	Yes		up to 64 characters
`projectId`	`string`	Yes		up to 64 characters
`label`	`string`	No		up to 100 characters
`linked`	`boolean`	No	`true`

Response 200

{
  version: {
    versionId: string
    spaceId: string
    name: string
    description: string
    startDate?: string
    releaseDate?: string
    released: boolean
    releasedAt?: number
    archived: boolean
    position: number
    data: {
      deployments?: {
        deploymentId: string
        projectId: string
        label?: string
        at: number
      }[]
    }
  }
}

`DELETE /v1/orgs/:orgId/issues/spaces/:spaceKey/versions/:versionId`

Deletes a version, optionally moving its issues to replaceWith.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, or an issue space's version (release, `ver_…`).

Query parameter	Type	Required	Notes
`replaceWith`	`string`	No	up to 64 characters

Response 200

{
  versionId: string
  updated: number
}

`GET /v1/orgs/:orgId/issues/spaces/:spaceKey/components`

Components of a space.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Response 200

{
  components: {
    componentId: string
    spaceId: string
    name: string
    description: string
    leadId?: string
    defaultAssignee: "space" | "lead" | "unassigned"
  }[]
}

`POST /v1/orgs/:orgId/issues/spaces/:spaceKey/components`

Creates a component (with an optional lead and default assignee).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).

Request body

Field	Type	Required	Notes
`description`	`string`	No	up to 2,000 characters
`leadId`	`string`	No	up to 64 characters; can be `null`
`defaultAssignee`	`"lead" \| "unassigned" \| "space"`	No
`name`	`string`	Yes	1–100 characters; trimmed

Response 201

{
  component: {
    componentId: string
    spaceId: string
    name: string
    description: string
    leadId?: string
    defaultAssignee: "space" | "lead" | "unassigned"
  }
}

`PATCH /v1/orgs/:orgId/issues/spaces/:spaceKey/components/:componentId`

Changes a component.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:componentId`	Component id (`cmp_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`description`	`string`	No	up to 2,000 characters
`leadId`	`string`	No	up to 64 characters; can be `null`
`defaultAssignee`	`"lead" \| "unassigned" \| "space"`	No

Response 200

{
  component: {
    componentId: string
    spaceId: string
    name: string
    description: string
    leadId?: string
    defaultAssignee: "space" | "lead" | "unassigned"
  }
}

`DELETE /v1/orgs/:orgId/issues/spaces/:spaceKey/components/:componentId`

Deletes a component and removes it from its issues.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:spaceKey`	Space key (`WEB`; former keys work too) or space id (`spc_…`).
`:componentId`	Component id (`cmp_…`).

Response 200

{
  componentId: string
  updated: number
}

Issue spaces

On this page