REST API

Scripts, integrations and other tools outside Jira can read and change TreeCraft hierarchies through the app's REST API. This page is for the developers who build them. It covers turning the API on, getting a token, the scopes, every endpoint, and the rules every call follows.

What the API is for

The API lets a program do what a person does on the app's pages, as that person. For example, it can:

• list the hierarchies someone can open, and read their rows;
• keep a hierarchy in step with another tool, by adding, moving and removing rows;
• create, rename, archive or delete hierarchies;
• read a hierarchy's rules and the saved views.

Every call acts as the person who authorized it, with the same checks as the app's own pages:

• their access level on the hierarchy: View, Edit, Automate or Control;
• the site's App access and Automation permissions;
• their Jira permissions for every work item.

A row never shows a work item the caller can't see in Jira. The API gives work item ids, not work item fields: read the work items themselves from Jira's own REST API with the same token, so Jira's permissions apply there too.

This is version 1, in beta. The API is built on Forge app REST APIs, which Atlassian offers as a Preview. Atlassian may change them at shorter notice than usual, so the API stays in beta until they are generally available.

It runs on Atlassian

Calls go through Atlassian's API gateway to the app, which runs on Atlassian's cloud like the rest of TreeCraft. The app sends no data outside Atlassian. What the API keeps, such as the record of a retried call, stays in the app's storage on Atlassian with the rest of the site's data. With the API on, TreeCraft is still built to Atlassian's Runs on Atlassian requirements.

The gateway checks the token and its scopes before the call reaches the app. A token without the scope a route needs never reaches TreeCraft.

Turn the API on

Two switches must be on for a call to reach the app. Both belong to the site, and turning off either one stops every call at once.

The first version of TreeCraft with the API is a major update of the app. A site admin approves that update once before the API is available.

Atlassian's switch

Atlassian's switch is off by default. A site admin or an organization admin turns it on:

1. Go to Atlassian Administration and select your organization.
2. Under Apps, go to Sites and select the site where TreeCraft is installed.
3. Select Connected apps, find TreeCraft, and select View app details.
4. On the Details tab, turn on App REST APIs.

TreeCraft's switch

TreeCraft's own switch is on by default. Jira admins and app admins find it in the app's settings, in Jira administration under Apps: select REST API in the Access group. The page has:

• Allow calls to this app's REST API on this site, the switch. A change reaches every call within a minute. While it is off, every call answers 403 API_TURNED_OFF.
• Base URL, both forms, filled in for your site, each with a copy button.
• Identifiers: the app id, the environment id and the cloud id.
• Scopes: the three scopes and what each one allows.

Get an access token

The API takes an OAuth 2.0 (3LO) access token. A token belongs to one person, and every call made with it acts as that person. Only members of the site where TreeCraft is installed can set up the integration.

1. Open the Atlassian Developer Console. Select Create, then OAuth 2.0 integration, and give it a name.
2. Under Permissions, select Add Marketplace or custom app. Pick your site, then TreeCraft, then the scopes your integration needs. Pick only those.
3. Also add the Jira scope read:forge-app:jira. Every call to an app's REST API needs it.
4. Under Authorization, set a callback URL. The console then shows an authorization URL.
5. Check that the URL's scope parameter lists the TreeCraft scopes and read:forge-app:jira. Add offline_access to get a refresh token. Add any missing scope by hand, separated by %20.
6. Open the URL, pick the site and select Accept. Atlassian sends you to the callback URL with a code.
7. Exchange the code for a token, as shown below.

An authorization URL that asks for the read scope looks like this:

https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=YOUR_CLIENT_ID&scope=read%3Ahierarchy%3Acustom%20read%3Aforge-app%3Ajira%20offline_access&redirect_uri=YOUR_CALLBACK&state=RANDOM&response_type=code&prompt=consent

Exchange the code for a token like this:

curl -s -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"authorization_code","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","code":"THE_CODE","redirect_uri":"YOUR_CALLBACK"}'

The answer holds access_token, which is short-lived, and refresh_token if you asked for offline_access. To get a new access token, send the refresh token in place of the code:

curl -s -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"refresh_token","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","refresh_token":"THE_REFRESH_TOKEN"}'

Send the token on every call, in the Authorization header:

curl -s "$BASE/v1/hierarchies" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

If the token lacks the scope a route needs, Atlassian's gateway refuses the call with 401 Unauthorized; scope does not match.

Base URL

Two forms of base URL reach the same API:

https://api.atlassian.com/svc/jira/<cloud-id>/apps/<app-id>_<environment-id>
https://<your-site>.atlassian.net/gateway/api/svc/jira/apps/<app-id>_<environment-id>

The parts in angle brackets are placeholders. Your own values are on TreeCraft's REST API page, which shows both URLs filled in, ready to copy.

Once Atlassian's switch is on, Atlassian Administration also shows the base URL under App REST APIs.

The examples on this page use two shell variables:

BASE='https://api.atlassian.com/svc/jira/<cloud-id>/apps/<app-id>_<environment-id>'
TOKEN='<access-token>'

Scopes

TreeCraft has three scopes. Each endpoint needs exactly one of them.

A scope never gives more than the person has. An integration that changes rows usually asks for read:hierarchy:custom too, so it can read what it changes. Every call also needs the Jira scope read:forge-app:jira.

Endpoints

Every path starts with the version, /v1. {id} is a hierarchy id and {viewId} a view id. The level is the person's access level on the hierarchy. Every call also needs App access to let the person use the app.

A hierarchy the person can't open answers 404, the same as one that doesn't exist. A level that is too low answers 403.

List hierarchies

GET /v1/hierarchies · Scope: read:hierarchy:custom · Needs: View on each hierarchy listed

Lists the hierarchies the person can open, ordered by id, one page at a time.

curl -s "$BASE/v1/hierarchies?limit=2" -H "Authorization: Bearer $TOKEN"

{
  "hierarchies": [
    { "id": 12, "name": "Release plan", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
      "archived": false, "version": 48, "labels": ["Planning"], "favorite": true, "searchable": false },
    { "id": 15, "name": "Support backlog", "description": "Open requests by team", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5",
      "access": "view", "archived": false, "version": 7, "labels": [], "favorite": false, "searchable": true }
  ],
  "nextCursor": "aDoxNQ"
}

Each hierarchy has these fields:

Create a hierarchy

POST /v1/hierarchies · Scope: manage:hierarchy:custom · Needs: App access lets the person create hierarchies

Creates a hierarchy. The person becomes its owner, with Control, and it is one of their favorites. Like any new hierarchy, it starts private.

curl -s -X POST "$BASE/v1/hierarchies" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: create-release-plan-1' \
  -d '{"name":"Release plan","description":"Everything planned for the next release"}'

Answers 201 with the new hierarchy:

{ "id": 21, "name": "Release plan", "description": "Everything planned for the next release", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5",
  "access": "control", "archived": false, "version": 0, "labels": [], "favorite": true, "searchable": false }

Get a hierarchy

GET /v1/hierarchies/{id} · Scope: read:hierarchy:custom · Needs: View

Reads one hierarchy's details. This call is cheap, so it is a good way to check version before reading the rows again.

curl -s "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN"

Answers 200 with the hierarchy, with the same fields as in the list:

{ "id": 12, "name": "Release plan", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
  "archived": false, "version": 48, "labels": ["Planning"], "favorite": true, "searchable": false }

Change a hierarchy

PATCH /v1/hierarchies/{id} · Scope: manage:hierarchy:custom · Needs: Control

Renames, describes, labels, archives or restores a hierarchy. Give at least one field.

The fields are applied one after another, as in the app. So a 400 for a bad name or description can come after the labels of the same request were already changed. Where that matters, send one field at a time.

curl -s -X PATCH "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Release plan 2027","labels":["Planning","2027"]}'

Answers 200 with the hierarchy as it is now:

{ "id": 12, "name": "Release plan 2027", "description": "", "ownerAccountId": "5b10ac8d82e05b22cc7d4ef5", "access": "control",
  "archived": false, "version": 48, "labels": ["Planning", "2027"], "favorite": true, "searchable": false }

Delete a hierarchy

DELETE /v1/hierarchies/{id} · Scope: manage:hierarchy:custom · Needs: Control

Deletes the hierarchy with its rows, rules and write-backs. The Jira work items are not changed. This can't be undone.

curl -s -X DELETE "$BASE/v1/hierarchies/12" -H "Authorization: Bearer $TOKEN"

Answers 204 with no body.

Read rows

GET /v1/hierarchies/{id}/rows · Scope: read:hierarchy:custom · Needs: View

Reads the tree, or the part below one row. Rows come in the order the grid shows them with nothing sorted: each row, then the rows below it.

curl -s "$BASE/v1/hierarchies/12/rows?depth=2&limit=5000" -H "Authorization: Bearer $TOKEN"

{
  "hierarchyId": 12,
  "version": 48,
  "building": false,
  "limitsReached": [],
  "rows": [
    { "id": 4711, "parentId": null, "level": 1, "kind": "issue", "byRule": false, "hasChildren": true, "issueId": "10001" },
    { "id": 4712, "parentId": 4711, "level": 2, "kind": "folder", "byRule": false, "hasChildren": false, "folderId": "7", "name": "Next quarter" },
    { "id": 4713, "parentId": 4711, "level": 2, "kind": "restricted", "byRule": false, "hasChildren": true },
    { "id": 4800, "parentId": null, "level": 1, "kind": "group", "byRule": true, "hasChildren": true, "groupId": "status:3", "label": "In Progress" }
  ],
  "nextCursor": null
}

Every row has these fields:

Then, by kind:

The answer also has:

• version: the hierarchy's version when the page was read.
• building: true while the rules' output is being rebuilt. Read again shortly for the newest rows.
• limitsReached: the rule limits that cut the rules' output, as the app's notice names them.

Each page reads the tree again, so ask for large pages. A hierarchy of 20,000 rows takes 4 calls of 5,000.

Change rows

POST /v1/hierarchies/{id}/rows/batch · Scope: write:hierarchy:custom · Needs: Edit, and Automate to move or remove rules

Adds, moves and removes rows in one batch. The app checks the whole batch first, then writes it as one change, or not at all. It is the same change, with the same checks, as editing in the app.

Each change has an action:

curl -s -X POST "$BASE/v1/hierarchies/12/rows/batch" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sync-2026-10-24-0900' \
  -d '{"changes":[
        {"action":"add","parentId":null,"afterId":4711,"items":[{"issueId":"10001"},{"folderName":"Next quarter"}]},
        {"action":"move","rowIds":[4712],"parentId":4800,"afterId":null},
        {"action":"remove","rowIds":[4713],"keepChildren":true}]}'

{
  "hierarchyId": 12,
  "version": 49,
  "added": [
    { "changeIndex": 0, "rowId": 6620417819, "kind": "issue", "issueId": "10001" },
    { "changeIndex": 0, "rowId": 2299815532, "kind": "folder", "folderId": "8" }
  ],
  "removedRowIds": [4713]
}

added lists the new rows, with the index of the change that added each one. The app chooses new row ids. removedRowIds lists only rows the person could see.

• The person must be able to see every row the batch names, the rows above it, and every work item it adds. Otherwise the batch answers 403 and changes nothing.
• A row that no longer exists answers 409 CONFLICT.
• A batch holds at most 200 changes, 2,000 rows and 50 new folders.
• A hierarchy holds at most 20,000 work items.
• Rows the person can't see below a removed row stay where they were, as in the app.
• New folders named by folderName are made before the change is written. If the batch is refused, they are deleted again.
• Changes inside the rules' output need the hierarchy's setting for it. See Changes inside rule output.
• A hierarchy with rules rebuilds their output afterwards, in the background.

List rules

GET /v1/hierarchies/{id}/rules · Scope: read:hierarchy:custom · Needs: Automate

Lists the hierarchy's rules in tree order, with their settings. It needs Automate, as rule settings do in the app.

curl -s "$BASE/v1/hierarchies/12/rules" -H "Authorization: Bearer $TOKEN"

{
  "hierarchyId": 12,
  "version": 48,
  "building": false,
  "limitsReached": [],
  "rules": [
    { "ruleId": "31", "rowId": 4800, "parentId": null, "position": 0, "type": "insertJql", "settings": { "type": "insertJql", "jql": "project = REL" } }
  ]
}

Each rule has its ruleId, its rowId in the tree, its parentId, its position among its siblings (from 0), its type, and its settings as the app keeps them. Later versions may add fields to settings.

List views

GET /v1/views · Scope: read:hierarchy:custom · Needs: no level on a hierarchy

Lists all of the person's own views and up to 100 shared views they may use.

curl -s "$BASE/v1/views?search=release" -H "Authorization: Bearer $TOKEN"

{
  "views": [
    { "id": 4, "name": "Release columns", "mine": true, "shared": true, "editable": true,
      "columns": [ { "id": "c1", "type": "field", "field": "status" } ], "wrap": false }
  ],
  "moreShared": false
}

mine is true for the person's own views, shared for views shared with others, and editable when the person may change the view in the app. columns lists its columns in order, as the app keeps them. moreShared is true when more shared views exist than were listed: search by name to find them.

Get a view

GET /v1/views/{viewId} · Scope: read:hierarchy:custom · Needs: no level on a hierarchy

Reads one view: one of the person's own, or a shared view they may use. Any other view answers 404.

curl -s "$BASE/v1/views/4" -H "Authorization: Bearer $TOKEN"

{ "id": 4, "name": "Release columns", "mine": true, "shared": true, "editable": true,
  "columns": [ { "id": "c1", "type": "field", "field": "status" } ], "wrap": false }

What the API never shows

• Work items the person can't see in Jira. Rows that rules placed and that the person can't see are left out, with everything below them. A work item placed by hand that the person can't see shows as a restricted row only where it holds rows they can see. That row says nothing about the work item. This holds for everyone, app admins included.
• Work item fields. The API gives work item ids. Read the work items from Jira's REST API with the same token.
• Email addresses. People appear by Atlassian account id only.
• Rules and their settings, to people without Automate on the hierarchy.

Errors

Every error has the same shape:

{ "error": { "status": 409, "code": "CONFLICT", "message": "row no longer exists" } }

429, 502 and 503 answers, and 409 IDEMPOTENCY_IN_PROGRESS, carry retryAfterSeconds in the body and a Retry-After header, both in seconds.

A token without the scope a route needs is refused by Atlassian's gateway, before the app, with 401 Unauthorized; scope does not match. That answer doesn't have the shape above.

Paging

Lists answer one page and a nextCursor. Pass it back as cursor to get the next page, until nextCursor is null. Cursors are opaque: don't build or change them.

If the row a page continues from is gone, the answer is 409 CURSOR_STALE. Start again from the first page.

Rate limits

Past a limit, the answer is 429 RATE_LIMITED with retryAfterSeconds. Atlassian applies its own rate limits to app REST APIs on top of these.

Each call also runs on your site's copy of the app. What it asks Jira counts against the app's hourly allowance of Jira API points on your site, which the app's pages share. Reading rows costs about the same as opening the hierarchy in the app. To keep the cost low:

• read with large pages;
• check a hierarchy's version with GET /v1/hierarchies/{id}, and read its rows again only when it changed;
• don't poll more often than you need.

Idempotency

POST, PATCH and DELETE take an optional Idempotency-Key header: 1 to 64 letters, digits, - and _. It makes a retry safe.

• The same key with the same request within 24 hours answers the first answer again, with the header Idempotent-Replayed: true. Nothing is done twice.
• The same key with a different request answers 422 IDEMPOTENCY_KEY_REUSED.
• The same key while the first call is still running answers 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Wait, then retry with the same key.
• A first try that failed with 401, 429 or a 5xx before it changed anything keeps nothing, so a retry with the same key runs it. After a 401, retry once the person has signed in or allowed the app again.
• A first try that failed after it changed something keeps its key. A retry with that key answers 409 IDEMPOTENCY_IN_PROGRESS for the first minute, then 409 IDEMPOTENCY_UNFINISHED: the first try ended without an answer. Read the hierarchy to see whether the change took effect. If it didn't, use a new key.
• A replay is the person's own first answer to that request, sent as it was. It is not checked against their access again.

Use a new key for each change you mean to make, and the same key to retry that change. Without a key, a retried POST may do its work twice: a second hierarchy, or rows added twice.

Versioning

• Paths carry the version: /v1. Within v1, changes only add things: new fields, optional parameters and new endpoints. Ignore fields you don't know.
• A change that would break callers makes /v2. v1 keeps working for at least 12 months after v2 is released. In that time, its answers carry Deprecation and Sunset headers.
• The scopes keep their meaning. A new scope means each integration asks its people to consent again.

Changelog

Planned next, in no promised order: computed column values for a view, work item keys in rows, rule changes, memos and planning items, history and tree queries.

Questions about the app? Write to info@plugincraft.ca.