PM API v1

Authentication

Mint a key under Settings → API Keys, give it the scopes it needs, and send it with every request. Three header forms carry the same token — use whichever your HTTP client makes easiest:

X-API-Key: <token>
Authorization: Bearer <token>
Authorization: token <token>

X-API-Key takes precedence whenever more than one is present. The third form matches GitHub's classic-PAT scheme, so tooling ported from GitHub works unchanged. Requests here are authenticated by key alone: browser cookies are never accepted on this namespace, so a call made from a logged-in browser behaves exactly like one from a server.

Scopes

A key carries one or more scopes, and every endpoint below names the one it requires. A write scope implies its read counterpart, and the older broad api scope satisfies all four, so a key minted before these existed keeps working unchanged.

A write scope needs a plan with API write access; a key that asks for one without it is refused at mint time rather than failing later on a live request.

Per-project keys

Instead of a global scope, a key can be granted access to named projects only. The grammar is:

project:<KEY>:read
project:<KEY>:write

A key holding only project:ACME:write can create and edit tasks in the ACME project and nothing else: GET /projects returns just that one project, and a task, sprint or epic belonging to any other project answers 404. Grants are made from the project picker under Settings → API Keys; a project's key or its id both work as the middle segment.

Pagination

List endpoints are cursor-paginated. Pass limit to size a page, then follow meta.nextCursor until meta.hasMore is false. A cursor encodes its own sort position, so pages stay stable while rows are written underneath you — never construct one yourself, and never assume a numeric offset.

curl -s "https://unityfreak.com/api/public/v1/projects/ACME/tasks?limit=50&cursor=$NEXT" \
  -H "X-API-Key: $UNITYFREAK_API_KEY"

Conditional requests

Every GET returns a weak ETag. Send it back as If-None-Match and an unchanged resource answers 304 Not Modified with no body. A 304 still counts as one request against your hourly quota — it saves bandwidth and parsing, never quota.

On the unsafe methods the same tag works the other way round: send it as If-Match and the write applies only if nobody has changed the resource since you read it, otherwise it answers 412 and nothing is modified.

Idempotency

Send an Idempotency-Key header on any POST and a retry carrying the same key and an identical body replays the first response — marked Idempotency-Replayed: true — instead of creating a second record. The same key sent with a different body, or to a different route, is rejected rather than silently doing the wrong thing; a duplicate that arrives while the first is still in flight is told to retry shortly.

Rate limits

Limits are per key, per hour, and follow the key owner's plan:

A limited key gets RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response, and 429 once the window is spent. A key on an unlimited plan is never counted and receives no RateLimit-* headers at all — their absence is how "no ceiling" is represented, because no legal header value means unlimited. Do not read a missing RateLimit-Remaining as zero. An individual key may also carry a lower ceiling of its own, which can only narrow the plan's, never raise it.

"Unlimited" describes the per-key hourly ceiling only. Every request to this namespace — including one that never carries a valid key — also passes a coarse, unauthenticated 100 requests per minute, per IP address limiter first, before your key is even validated. That limiter is shared across every integration calling from the same address, replies with 429 and { error: { code: "RATE_LIMITED" } } rather than this API's own RATE_LIMIT_EXCEEDED, and is not affected by your plan. A Team/Enterprise key is unlimited per key, but still subject to this per-IP ceiling.

Polling for changes

GET /tasks returns tasks across every project a key can see and accepts an updatedSince filter — this is how you keep an external system in step without running a webhook receiver.

Ordinary updatedSince listing filters on task updatedAt and its boundary is inclusive: page through a cycle, then retain the largest updatedAt you consumed and de-duplicate on id at that boundary. An empty page carries no new checkpoint — keep the updatedSince you already have; there is nothing new to advance to. Trigger polling (trigger=created or trigger=updated) instead reads the immutable feed ordered by revision, filters by inclusive publishedAt, and returns each item’s revision/changeKind/publishedAt metadata. Follow meta.nextCursor until meta.hasMore is false; only that terminal response includes X-UF-Polling-Checkpoint, which begins the next immutable window — unlike ordinary listing, this checkpoint always advances to the end of the polled window even when the page was empty, because it is bounded by feed revision, not by which rows were returned. Do not use a clock value such as HTTP Date. Delivery is at-least-once and never silently lossy. meta deliberately contains only nextCursor/hasMore, nothing time-varying, so this endpoint can actually 304 on an unchanged page.

# $CHECKPOINT is the largest updatedAt you saw in the last full cycle.
curl -s "https://unityfreak.com/api/public/v1/tasks?updatedSince=$CHECKPOINT&limit=100" \
  -H "X-API-Key: $UNITYFREAK_API_KEY"

Status codes

Every non-2xx response carries the same envelope — { "error": { "code", "message", "status" } } — so a client can branch on error.code without parsing prose.

Endpoint reference

Generated from the OpenAPI document, so this is the API rather than a description of it. Paths are relative to https://unityfreak.com/api/public/v1.

# The namespace root is unauthenticated — a one-call connectivity check.
curl -s https://unityfreak.com/api/public/v1/

# List every project this key can see.
curl -s https://unityfreak.com/api/public/v1/projects \
  -H "X-API-Key: $UNITYFREAK_API_KEY"

# Create a task. Safe to retry: the same Idempotency-Key never creates twice.
curl -s -X POST https://unityfreak.com/api/public/v1/projects/ACME/tasks \
  -H "X-API-Key: $UNITYFREAK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Fix login redirect"}'

# List a project's sprints.
curl -s https://unityfreak.com/api/public/v1/projects/ACME/sprints \
  -H "X-API-Key: $UNITYFREAK_API_KEY"

# Read an epic by id.
curl -s https://unityfreak.com/api/public/v1/epics/$EPIC_ID \
  -H "X-API-Key: $UNITYFREAK_API_KEY"

Machine-readable spec

The full OpenAPI 3.0 document — request and response schemas, every status code, every header — is public and needs no key. Point a generator at it rather than hand-writing a client.

openapi.json