API overview

Strategy Hub exposes a REST API for reading and writing Strategic Items, Types, Statuses, Status Sets, and Labels from outside Jira. This page covers what every endpoint has in common — authentication, scopes, error handling, and rate limits — so the API reference only has to describe what’s unique to each endpoint.

Authentication#

The API authenticates with Atlassian’s 3LO OAuth 2.0 (authorization code) flow. Your integration directs a user through Atlassian’s authorization URL, exchanges the returned code at Atlassian’s token URL, and calls the API with the resulting bearer token in an Authorization: Bearer <token> header. Every call acts as that authenticated user — it sees and edits only what their Jira permissions and Strategy Hub access already allow.

The exact base URL for every endpoint is shown in the API reference.

Scopes#

Request only the scopes your integration needs when starting the OAuth flow.

Scope	Grants
read:items:custom	Read Items, their details, children, and search results
write:items:custom	Create, update, archive, and restore Items
read:config:custom	Read Types, Statuses, Status Sets, and Labels
write:config:custom	Create, update, and delete Types, Statuses, Status Sets, and Labels
read:notifications:custom	Read a user’s notifications and unread counts

Errors and rate limits#

Every error response shares one shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "startDate must be an ISO date"
  }
}

code is a stable machine-readable string — safe to match on in your integration. message is a human-readable detail that can change without notice.

Code	Meaning
VALIDATION_ERROR	The request body or query parameters failed validation.
NAME_EMPTY	A required name field was blank.
USER_ID_MISSING	The request needed a user (an Owner, for example) that wasn’t supplied.
NOT_FOUND	The referenced Item, Type, Status, Status Set, or Label doesn’t exist.
FORBIDDEN	The authenticated user’s permissions don’t allow this action.
INVALID_CHILD_TYPE	The child Item’s Type isn’t allowed under the given parent Type.
HIERARCHY_VIOLATIONS	The change would break the Type hierarchy’s parent/child rules.
CONFIG_MODE_VIOLATIONS	The change conflicts with the workspace’s configuration mode.
STATUS_SET_ORPHAN_WARNING	The change would leave a Status Set with no Items referencing it.
LABEL_COLLISION	A Label with that name already exists.
NOT_INITIALIZED	The workspace hasn’t finished setup yet.
RATE_LIMITED	Too many requests. Back off and retry after a short delay.
DATABASE_ERROR	An unexpected storage error. Retry, and open a support request if it persists.
UNKNOWN_ERROR	An unexpected server error. Retry, and open a support request if it persists.

A RATE_LIMITED response (HTTP 429) means your integration is calling the API faster than its limit allows. Reduce request frequency and add a short backoff before retrying.

Quickstart#

Once you have an access token, list Items with a single authenticated request:

curl "<base-url>/items" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

Replace <base-url> with the base URL shown in the API reference and <access-token> with the bearer token from your OAuth exchange.

Related#

• API reference — every endpoint, request, and response schema.
• Strategic Items — what an Item is and how it’s structured, independent of the API.
• Access and permissions — how Custom access and system roles shape what an authenticated call can see or change.