Work with Spaces

Learn how to look up an existing Jira space by key and create new spaces using Projects.getByKey and Projects.create.

With HAPI, you can look up and create Jira spaces through a typed API. Jira spaces were previously called projects, so the methods are in the Projects module.

Pattern for getting a space by key

When you need to look up an existing space, you can follow this basic pattern:

Import Projects from @scriptrunnerhq/hapi/projects.
Call Projects.getByKey with the space key.
Check whether a project was returned.
Use its properties (for example, name), or handle the "not found" case.

The following example shows this general pattern:

import * as Projects from '@scriptrunnerhq/hapi/projects'
 
export default async function () {
  const project = await Projects.getByKey('SPACE_KEY')
 
  if (!project) {
    throw new Error('Space not found')
  }
 
  return `Project: ${project.name}`
}

Use this pattern when you need to validate that a space exists before creating work items, or when you want to read basic metadata (such as the project name) for display or logging.

Pattern for creating a space

When you need to create a new space, you can follow this basic pattern:

Import Projects from @scriptrunnerhq/hapi/projects.
Call Projects.create with:
- A unique project key.
- A human‑readable name.
- A projectTypeKey (for example, 'software').

The following example shows this general pattern:

import * as Projects from '@scriptrunnerhq/hapi/projects'
 
export default async function () {
  const result = await Projects.create({
    key: 'NEWKEY',
    name: 'New Space',
    projectTypeKey: 'software',
  })
 
  return result
}

Use this pattern when you want to provision new spaces programmatically as part of setup or automation, or need consistent naming/keys for projects created by your app.

In-app example scripts

The following examples are available in-app:

Get a space by key: Shows how to use Projects.getByKey to retrieve a space by its key and return its name, throwing an error if the space does not exist.
Create a space: Shows how to use Projects.create to create a new Jira space with a specified key, name, and projectTypeKey (for example, 'software').