API Reference
The TruePPM REST API is documented via OpenAPI 3.0.3, auto-generated by drf-spectacular.
Interactive schema
Section titled “Interactive schema”| Format | URL |
|---|---|
| Swagger UI | http://localhost:8000/api/schema/swagger-ui/ |
| Raw YAML | http://localhost:8000/api/schema/ |
Base URL
Section titled “Base URL”http://localhost:8000/api/v1/In this section
Section titled “In this section”- API authentication — logging in, refreshing and revoking access tokens, project-scoped API tokens, personal access tokens, and single sign-on.
- Projects, members and workspace API — calendars, projects, project members, and workspace members, invites and groups.
- Programs API — programs, program membership sync, and the program backlog.
- Tasks and dependencies API — tasks, attachments, dependencies, cross-project slip conflicts, Monte Carlo, task relations, acceptance criteria and recurrence rules.
- Project templates and import API — project templates, import templates, and import provenance.
- Sprints and estimation API — sprint cadence generation, sprint–milestone binding, scope and duration changes, estimation poker, retro items and velocity suggestions.
- Resources and time API — resources, task-resource assignments, the project roster, teams, skills, and time tracking.
- Webhooks, sync and sharing API — webhooks, offline sync, integrations, notification preferences, mention groups, assets, public share links, agent actions and user search.
These pages are a curated tour, not an exhaustive endpoint dump — the interactive schema is complete, and several groups get only a pointer to the feature page that covers them.
Admin: failed tasks
Section titled “Admin: failed tasks”/api/v1/admin/failed-tasks/ (list, retrieve, requeue, drop, requeue-all,
drop-all) is the Celery dead-letter queue surface, fully documented in
System health.
Admin: workflows
Section titled “Admin: workflows”Readiness probe
Section titled “Readiness probe”| Method | Path | Description |
|---|---|---|
| GET | /api/v1/readyz | Dependency-aware readiness for Kubernetes readiness/startup probes. Unauthenticated by design (kubelet sends no credentials). Coarse {"status": "ok"|"fail", "checks": {...}, "migration_state": "in_sync"} body with no infrastructure detail; 200 when every checked dependency is healthy, 503 otherwise |
migration_state reports which way the pod’s migrations differ from the recorded
schema: behind (this image ships migrations the database has not applied — the
rolling-forward window), ahead (the database records migrations this image does
not ship), unknown (the check itself failed), or in_sync.
behind and unknown always make the pod not-ready. ahead gates the pod only
when it booted into that state — the rollback case. A pod that booted in sync
and drifted to ahead while serving is the ordinary rolling upgrade, and stays
ready so the Service is not emptied while the new pods come up; the state is
still reported either way. An operator can also re-open the gated case with
TRUEPPM_READYZ_ALLOW_DB_AHEAD for a deliberate additive-only rollback, which
changes readiness without hiding the state. checks keeps its existing keys and
its ok/fail values, so a scraper reading only status/checks is unaffected.
ahead is a schema-presence signal, not a data-compatibility verdict — see
rollback.
Distinct from the plain unauthenticated liveness check at /api/v1/health/
and the admin-only, deeper /health/system/ used by
System health — readyz is the one
Kubernetes should point a readiness probe at.
Pagination
Section titled “Pagination”Four pagination dialects ship today; a fifth, keyset on the task list, ships in 0.5. The generated OpenAPI schema is authoritative per endpoint: read the parameters the operation declares rather than assuming one convention.
| Dialect | Query parameters | Response envelope | Used by |
|---|---|---|---|
| Page number | page | {count, next, previous, results} | Most list endpoints (default page size 50) |
| Page number with size | page, page_size | {count, next, previous, results} | Endpoints that let you choose the page size, such as /admin/failed-tasks/ |
Cursor (DRF CursorPagination) | cursor, page_size (default 50, maximum 200) | {next, previous, results}, no count | Only the audit log, the workspace member list, and a webhook’s delivery history |
| Keyset (task list, opt-in) | pagination=keyset, cursor, page_size (maximum 500) | {next, previous, results}, no count | GET /tasks/; ships in 0.5 |
| Limit and offset | limit, offset | {count, next, previous, results} | /me/work/, /me/external-items/, the product backlog and the API token audit lists |
Several other endpoints also declare cursor and page_size, but they are not DRF
cursor paginators and do not return {next, previous, results}: the asset feeds
(/assets/, /programs/{program_pk}/assets/, /projects/{project_pk}/assets/) and the
project changelog (/projects/{project_pk}/changelog/) return {results, next_cursor},
and the sync pulls (/projects/{id}/sync/, /sync/user/programs/) return
{changes, timestamp, next_cursor, ...}. For these, pass next_cursor back as
cursor until it is null; the cursor is opaque.
A sixth, bespoke shape, {results, next_until}, is used by the board activity feed
(/projects/{id}/board/activity/): pass the returned next_until back as the
upper time bound of the next request.
Page-number response:
{"count": 123, "next": "...?page=3", "previous": "...?page=1", "results": [...]}The task list ships an opt-in keyset mode in 0.5: GET /tasks/?pagination=keyset
returns {next, previous, results} with no count, in the default WBS order
(numeric per level, then name, then id). Follow next until it is null, passing
its cursor value back unchanged; page_size is honored up to 500, previous is
always null, and combining it with ordering returns 400. Unlike page numbers,
a keyset walk neither repeats nor skips a row when tasks are plainly added or removed
between requests, and a deep page costs about what the first one does. A structural
move (such as indent, outdent, reparent, group, ungroup) or a rename during a walk changes the sort key of
rows already served, so it can repeat or skip a row; restart the walk if that matters. The response schema marks count required for both modes; keyset responses omit it (tracked in #5053). Without
pagination=keyset the endpoint keeps its page-number envelope.
Cursor endpoints cover unbounded, append-only logs. A cursor envelope has no
count (computing one would defeat the point of a cursor), so it is
{next, previous, results} only. Follow next until it is null; do not
compute page counts from these endpoints, and treat the cursor value as opaque.
The dialects above are a pre-1.0 inconsistency, not a design. One convention will be chosen for 1.0; until then, a client should not assume the dialect from the endpoint’s neighbors.
Not every list endpoint is paginated. Some return a bare array where the
result set is inherently small and bounded — a task’s
relations, for instance. The generated
OpenAPI schema is authoritative per endpoint: check the
declared 200 response shape rather than assuming an envelope.
Rate limiting
Section titled “Rate limiting”Every endpoint is rate limited. A general default applies to any endpoint that does not declare a stricter, endpoint-specific limit:
| Caller | Default limit | Bucketed by |
|---|---|---|
| Unauthenticated | 60 requests / minute | Client IP |
| Authenticated | 1000 requests / minute | Account |
Both defaults are operator-configurable (TRUEPPM_THROTTLE_ANON_RATE and
TRUEPPM_THROTTLE_USER_RATE; see
Configuration).
/api/v1/health/and/api/v1/edition/are exempt. They are never rate limited, so a Kubernetes liveness loop is not throttled./api/v1/readyzis not exempt — unlike those two it does a real database and cache round-trip per call, so it gets its own dedicated, generous scope (readyzin the table below) instead of a full exemption, to bound an unauthenticated caller who reaches the pod IP directly (the probe path bypasses the Ingress).- Scoped endpoints replace the default. An endpoint with its own limit carries only that specific limit — scoped limits do not stack on top of the general default (two different scoped throttles on the same endpoint, e.g. task-sync’s per-project limit, do stack with each other).
Complete scoped-throttle list
Section titled “Complete scoped-throttle list”Two mechanisms implement a scoped limit. Most are a named entry in
DEFAULT_THROTTLE_RATES (env-tunable via the TRUEPPM_THROTTLE_* variable
named alongside each one below, where one exists); a handful of endpoints
that need bespoke logic (a sliding ramp-up window, two stacked buckets, a
Redis-atomic counter) are hand-rolled throttle classes instead. Both kinds
return 429 with the same Retry-After envelope shown above.
Scoped rates (DEFAULT_THROTTLE_RATES):
| Scope | Rate | Applies to |
|---|---|---|
anon | 60/min (TRUEPPM_THROTTLE_ANON_RATE) | General default, unauthenticated |
user | 1000/min (TRUEPPM_THROTTLE_USER_RATE) | General default, authenticated |
readyz | 2000/min (TRUEPPM_THROTTLE_READYZ_RATE) | /api/v1/readyz — its own scope, not the shared anon bucket, since its traffic comes from kubelet hitting the pod IP directly rather than through the Ingress |
login | 10/min | Login, per client IP |
login_account | 5/min (TRUEPPM_THROTTLE_LOGIN_ACCOUNT_RATE) | Login, per submitted username — stacks with login |
password_reset | 5/min | Password-reset request + confirm |
refresh | 60/min | JWT refresh |
user_search | 60/min | Member-invite user typeahead |
omni_search | 60/min (TRUEPPM_THROTTLE_OMNI_SEARCH_RATE) | ⌘K Epic/Story omni-search |
resolve | 120/min (TRUEPPM_THROTTLE_RESOLVE_RATE) | Key resolver and key suggestion (/resolve/, /keys/), per account |
ws_ticket | 120/min | WebSocket connection-ticket minting |
invite_resend | 5/min | Workspace invite resend |
email_settings | 12/min | Workspace SMTP config writes |
email_settings_probe | 6/min | SMTP send-test + deliverability probe |
oidc_discover | 30/min | SSO domain discovery |
oidc_login | 20/min | SSO login start |
oidc_callback | 30/min | SSO callback |
sso_test_connection | 20/min | SSO admin “Test connection” |
sso_provider_write | 20/min | SSO provider create/update/delete (reads exempt) |
credential_rotate | 10/min | Personal integration credentials + Git webhook secret rotation |
external_sync | 20/min | Manual external-connection pull trigger |
monte_carlo | 10/min | Monte Carlo run (POST .../monte-carlo/; synchronous through 0.4, queued on a worker from 0.5) |
monte_carlo_whatif | 6/min | Monte Carlo what-if (two CPM + two MC passes per call) |
cpm_on_read | 60/min (TRUEPPM_THROTTLE_CPM_ON_READ_RATE) | Schedule derivation read (a full CPM pass per call) |
program_schedule | 60/min (TRUEPPM_THROTTLE_PROGRAM_SCHEDULE_RATE) | Merged program schedule read (one CPM pass over every member project per call) |
burn | 60/min (TRUEPPM_THROTTLE_BURN_RATE) | Burn chart + flow metrics reads (shared bucket — both replay HistoricalTask) |
sample_load | 6/min (TRUEPPM_THROTTLE_SAMPLE_LOAD_RATE) | Bundled-sample demo loader |
seed_import | 6/min (TRUEPPM_THROTTLE_SEED_IMPORT_RATE) | Caller-supplied program seed import |
seed_validate | 20/min (TRUEPPM_THROTTLE_SEED_VALIDATE_RATE) | Seed import dry run |
sample_download | 60/min (TRUEPPM_THROTTLE_SAMPLE_DOWNLOAD_RATE) | Bundled-fixture file download |
mcp_read | 120/min (TRUEPPM_THROTTLE_MCP_READ_RATE) | Per-token baseline on any MCP-readable view |
mcp_read_compute | 12/min (TRUEPPM_THROTTLE_MCP_READ_COMPUTE_RATE) | Stacks on mcp_read for the compute-heavy MCP reads (what-if, latest Monte Carlo, forecasts, schedule derivation, program schedule) |
share_mint | 20/min (TRUEPPM_THROTTLE_SHARE_MINT_RATE) | Minting a public board/schedule share link |
share_access | 60/min (TRUEPPM_THROTTLE_SHARE_ACCESS_RATE) | Resolving a public share link |
status_update_post | 20/min (TRUEPPM_THROTTLE_STATUS_UPDATE_POST_RATE) | Posting a project status update, per account |
status_update_post_project | 20/min (TRUEPPM_THROTTLE_STATUS_UPDATE_POST_PROJECT_RATE) | Posting a project status update, per project (every poster shares the bucket) |
telemetry_test | 6/min | Telemetry test-export probe |
git_webhook_ip | 600/min (TRUEPPM_THROTTLE_GIT_WEBHOOK_IP_RATE) | Inbound Git webhook receiver, per client IP — stacks with GitWebhookThrottle below |
Hand-rolled throttle classes (custom windows/keys DRF’s scope rates can’t express):
| Class | Rate | Applies to |
|---|---|---|
TaskSyncThrottle | 100/min steady, 1000/min in the first 60 min after token mint | Inbound task-sync, per project |
AcceptanceResultThrottle | Same ramp as TaskSyncThrottle | CI acceptance-result ingest, per token |
TokenIssuanceThrottle | 5/min (TRUEPPM_TOKEN_ISSUANCE_PER_MINUTE) | Minting any API token, per user |
TaskAttachmentUploadThrottle | 60/min | Task-attachment upload, per user |
SyncUploadThrottle | 60/min per (project, user) and 120/min per user | Offline sync push — fails closed (429) on a Redis outage, the one throttle in this table that does |
GitWebhookThrottle | 120/min | Inbound Git webhook receiver, per project — the caller picks the project ID out of the URL, so this is stacked with the per-IP git_webhook_ip scope above and neither bounds the endpoint alone |
TaskLinkRefreshThrottle | 30/min | Manual task-link refresh, per user |
MentionRateThrottle | 100/hour and 1000/day | Comment @mention fan-out, per user (both windows apply) |
MembershipGrantThrottle | 60/min | Granting project or program membership, per user — shared budget across both surfaces (rate set inline, not DEFAULT_THROTTLE_RATES); does not bound role changes or removal |
Every hand-rolled class fails open on a Redis error (never blocks
legitimate traffic during a cache outage) except SyncUploadThrottle, which
fails closed — a denied offline sync retries with backoff, while an
unbounded write-path throttle bypass during an outage was judged the worse
failure mode.
When a caller exceeds a limit the API responds with 429 Too Many Requests and
a Retry-After header giving the number of seconds to wait before retrying:
HTTP/1.1 429 Too Many RequestsRetry-After: 42Content-Type: application/json
{"detail": "Request was throttled. Expected available in 42 seconds."}Clients should honor Retry-After and back off; retrying before it elapses
consumes no additional quota but continues to return 429.
Status codes
Section titled “Status codes”| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted — the work was queued and runs asynchronously (e.g. MS Project / Jira / CSV import, workspace/program/project export, invite-email (re)queueing, a task-run cancellation request). The response carries a job/status resource to poll, or a bare {"queued": true}, not the final result |
| 204 | No content (delete) |
| 207 | Multi-status — the rows of a batch were applied independently, so the body reports applied, rejected, and skipped together rather than one verdict for the whole request (batch task writes). A 207 does not mean every row succeeded: always read rejected |
| 304 | Not modified — the caller’s If-None-Match matched the current ETag (public share-link resolution; bundled-sample file download); the body is empty, refetch is unnecessary |
| 400 | Validation error |
| 401 | Missing or invalid token |
| 403 | Insufficient role |
| 404 | Not found or soft-deleted |
| 409 | Conflict (e.g. duplicate membership, sync id collision) |
| 410 | Gone — the resource existed but is deliberately no longer reachable and never will be again: a revoked public share link, or a completed workspace/program/project export download link past its expires_at. Distinct from 404 (never existed, or the caller cannot see it) |
| 413 | Payload too large — the workspace branding-logo upload exceeds its 2 MB ceiling, or an inbound Git webhook body exceeds its 1 MB cap |
| 415 | Unsupported media type (attachment upload outside the MIME allow-list) |
| 422 | Well-formed but unprocessable (idempotency-key reuse, program-schedule limits) |
| 429 | Rate limit exceeded — general default or a scoped throttle; includes a Retry-After header |
| 501 | Not implemented by this deployment’s configured backend |
| 502 | An upstream identity provider could not be reached |
| 503 | Service unavailable — a dependency-aware readiness/health check reports a failing dependency (/api/v1/readyz, /health/system/, /health/beat/), or an aggregation endpoint’s per-section subservice failed and degraded gracefully (e.g. the integrations-summary view, whose body then carries a failed key naming the section so the client falls back to that section’s own endpoint) |
Errors come in two shapes: field-keyed validation messages with no machine
code, and structured bodies carrying a stable code you can branch on. See
Errors and status codes for the full code table, the extra keys
each carries, and which of them the stability contract covers.