# API overview

> Authenticate against the Strategy Hub REST API, read its error and scope conventions, and make your first request

Canonical: https://docs.caskcode.io/strategy-hub/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](https://docs.caskcode.io/strategy-hub/api) 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](https://docs.caskcode.io/strategy-hub/api).

## 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:

```json
{
  "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:

```bash
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](https://docs.caskcode.io/strategy-hub/api) and `<access-token>` with the bearer token from your OAuth exchange.

## Related

- [API reference](https://docs.caskcode.io/strategy-hub/api) — every endpoint, request, and response schema.
- [Strategic Items](https://docs.caskcode.io/strategy-hub/items) — what an Item is and how it's structured, independent of the API.
- [Access and permissions](https://docs.caskcode.io/strategy-hub/access-and-permissions) — how Custom access and system roles shape what an authenticated call can see or change.