The REST API

Authenticating

• Base URL — https://your-domain.com/api/v1
• Header — Authorization: Bearer fk_live_.... The token already belongs to this workspace; no other header is needed.
• Replies come as { "success": true, "data": … }; on failure { "success": false, "error": { "statusCode", "message" } }.
• Lists are paged: page from 1 and limit up to 100; data.meta.totalPages says how many.

Examples

curl "https://your-domain.com/api/v1/work-items?projectKey=WEB&statusKeys=todo,in_progress&sortBy=updatedAt&sortDir=desc&limit=100" \
  -H "Authorization: Bearer fk_live_..."

curl "https://your-domain.com/api/v1/work-items/WEB-42" \
  -H "Authorization: Bearer fk_live_..."

curl -X PATCH "https://your-domain.com/api/v1/work-items/WEB-42" \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"statusKey":"in_progress"}'

curl -X PATCH "https://your-domain.com/api/v1/work-items/WEB-42" \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"assigneeId":"<user id>","priority":"HIGH"}'

curl -X POST "https://your-domain.com/api/v1/work-items/WEB-42/comments" \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"body":"Investigating now.","visibility":"INTERNAL"}'

curl -X POST "https://your-domain.com/api/v1/work-items" \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"projectKey":"WEB","type":"BUG","title":"Checkout fails on Safari"}'

Valid values

• Statuses — GET /boards/projects/WEB → data.statuses[].key. If the workflow lists transitions (GET /workflows), only those moves are accepted; others get 400 This workflow transition is not allowed.
• Priorities — GET /priorities: URGENT, HIGH, MEDIUM, LOW.
• Assignees — GET /members → user.id.
• Filters on GET /work-items — projectKey, statusKeys, priorities, assigneeIds (unassigned allowed), types, search, createdFrom/createdTo, sortBy/sortDir.
• Rate limit — about 120 requests a minute; a 429 means wait and retry.

Hearing about changes

Rather than polling, add a webhook in Settings → Outbound webhooks: Issue created, updated, status changed, assigned, resolved, comment added, and sprint started/completed and release shipped. Each delivery is a JSON POST signed with the webhook's secret in X-Forge-Signature: sha256=…; X-Forge-Delivery is the same on retries, so duplicates can be dropped.

import hashlib, hmac

def is_genuine(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Common endpoints