Work with Spaces

With HAPI, you can look up and create Jira spaces (projects) through a simple, typed API. This page walks you through working with spaces using HAPI's Projects.getByKey and Projects.create functions.

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').