buildr-plannr
Menu
Start free

API documentation

API docs for tasks, agents, and MCP.

Build integrations against buildr-plannr workspaces, projects, tasks, feature groupings, agents, imports, exports, and audit diagnostics with scoped auth, copyable examples, version notes, rate limits, pagination rules, idempotency guidance, customer-safe error handling, and legacy /api/issues compatibility notes.

Start free to create API tokenAPI support

API and MCP first decision

Read ready work first. Enable writes only after proof.

Coding tools should start with read-only MCP calls, then move to scoped task writes after owners approve permissions and evidence requirements.

MCP read first

Codex, Claude Code, Cursor, and Cowork should call search_tasks and read taskHealth before writes.

Open MCP quickstart

API tokens

Use scoped tokens for tasks, agents, imports, exports, audit, and billing-safe reads.

Review limits

Writes wait

Create or move tasks only after scope, files, approvals, quota, and proof are clear.

Open agents API

Need help

Use support for token setup, MCP client configuration, or blocked API access.

API support

API documentation summary

Sections

9

Endpoints

21

Versions

2

Error codes

7

Documentation contents

Endpoint groups

Auth, workspaces, projects, tasks, features, agents, imports, exports, and audit APIs are documented from the integration contract outward. Existing issue-named scopes and paths remain supported for older clients.

Authentication API

Human users authenticate with the custom Cognito-backed auth flow. Agents use scoped Bearer tokens or x-api-key headers that are tied to plans, workspaces, agents, scopes, and rate limits.

2 endpoints
  • Session cookie: buildr_plannr_session for local development or Cognito token cookies in deployed environments.
  • Agent token: hashed token material with workspace, agent, actor type, scopes, rate limits, and disabled or revoked state.
  • Authentication failures are audited without storing raw tokens or secrets.
POST/api/auth/login

Starts a custom login flow and returns the user to the requested protected path when authentication succeeds.

Workspace session

Login request

bash
curl -X POST https://app.buildr.example.com/api/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"owner@example.com","password":"not-logged"}'

Login response

json
{
  "data": {
    "redirectTo": "/app",
    "mode": "cognito"
  }
}

Errors

400 invalid-input, 401 unauthorized

Pagination

Not paginated.

Idempotency

Login attempts are not idempotent. Clients should retry only after user action.

POST/api/api-keys

Creates a scoped API token for an agent, automation, or user integration when the workspace plan allows API access.

Workspace session

Create API key

bash
curl -X POST https://app.buildr.example.com/api/api-keys \
  -H "content-type: application/json" \
  -b "buildr_plannr_session=..." \
  -d '{"label":"QA agent","workspaceId":"workspace-buildr","agentId":"agent-qa","planId":"pro","scopes":["issues:read","agents:execute"]}'

API key response

json
{
  "data": {
    "apiKey": {
      "id": "api-key-qa-agent",
      "workspaceId": "workspace-buildr",
      "agentId": "agent-qa",
      "scopes": ["issues:read", "agents:execute"],
      "rateLimit": { "requestsPerMinute": 600, "burst": 1200 }
    },
    "token": "buildr_live_..."
  }
}

Errors

400 invalid-input, 403 forbidden

Pagination

Not paginated.

Idempotency

Key creation is not idempotent. Store the returned token immediately because it is shown once.

Workspaces API

Workspace endpoints list, create, and update secured planning environments for teams and their agents.

2 endpoints
  • Workspace records include id, name, ownerId, status, defaultSandbox, and timestamps.
  • Workspace mutation requires a signed-in user session.
GET/api/workspaces?q=buildr

Lists workspaces visible to the authenticated session.

Workspace session

List workspaces

bash
curl https://app.buildr.example.com/api/workspaces?q=buildr \
  -b "buildr_plannr_session=..."

Workspace list

json
{
  "data": [
    {
      "id": "workspace-buildr",
      "name": "Buildr Plannr",
      "status": "active",
      "ownerId": "user-damien",
      "defaultSandbox": "workspace-write"
    }
  ]
}

Errors

401 unauthorized

Pagination

Workspace list responses are currently small and unpaginated. Future versions will add cursor and limit.

Idempotency

No idempotency key required.

POST/api/workspaces

Creates a workspace shell before projects and agent policies are attached.

Workspace session

Create workspace

bash
curl -X POST https://app.buildr.example.com/api/workspaces \
  -H "content-type: application/json" \
  -b "buildr_plannr_session=..." \
  -d '{"name":"Design partner workspace","ownerId":"user-owner"}'

Workspace created

json
{
  "data": {
    "id": "workspace-design-partner",
    "name": "Design partner workspace",
    "status": "active",
    "ownerId": "user-owner",
    "defaultSandbox": "workspace-write"
  }
}

Errors

400 invalid-input, 401 unauthorized

Pagination

Not paginated.

Idempotency

Workspace create is not idempotent. Use a client-side request key in your own workflow until server idempotency is added.

Projects API

Project endpoints group issues, milestones, and agent readiness around a product goal inside one workspace.

2 endpoints
  • Project records include workspaceId, goal, status, and timestamps.
  • Milestones use /api/milestones and are documented as project delivery slices.
GET/api/projects?workspaceId=workspace-buildr&q=agent

Lists projects for a workspace and optional search query.

Workspace session

List projects

bash
curl "https://app.buildr.example.com/api/projects?workspaceId=workspace-buildr&q=agent" \
  -b "buildr_plannr_session=..."

Project list

json
{
  "data": [
    {
      "id": "project-agent-foundation",
      "workspaceId": "workspace-buildr",
      "name": "Agent-first planning foundation",
      "status": "active",
      "goal": "Define the planning model for work agents can safely execute."
    }
  ]
}

Errors

401 unauthorized

Pagination

Use workspaceId and q to narrow results. Cursor pagination is reserved for larger remote datasets.

Idempotency

No idempotency key required.

PATCH/api/projects

Updates project status or goal metadata.

Workspace session

Update project

bash
curl -X PATCH https://app.buildr.example.com/api/projects \
  -H "content-type: application/json" \
  -b "buildr_plannr_session=..." \
  -d '{"projectId":"project-agent-foundation","status":"active"}'

Project updated

json
{
  "data": {
    "id": "project-agent-foundation",
    "status": "active",
    "updatedAt": "2026-05-22T13:00:00.000Z"
  }
}

Errors

400 invalid-input, 401 unauthorized, 404 not-found

Pagination

Not paginated.

Idempotency

PATCH is safe to retry with the same payload; unchanged fields are returned as-is.

Tasks API

Task endpoints are the primary integration surface for human work, clear task briefs for agents, comments, proof, approvals, dependencies, and status changes. REST paths and scope names still use /api/issues and issues:* for API compatibility.

3 endpoints
  • Task records include project, milestone, status, priority, labels, dependencies, agent instructions, acceptance checks, and proof.
  • Existing clients can keep using issue-shaped response fields while new MCP clients should prefer task-named tools and task response aliases.
  • Detail responses include nextAction, comments, activity, and dependency graph context.
GET/api/issues?projectId=project-agent-foundation&status=ready&includeDependencyGraph=true

Searches tasks by workspace, project, milestone, status, priority, label, dependency state, assigned agent, and text query. The legacy REST path remains /api/issues.

Workspace session

Search tasks

bash
curl "https://app.buildr.example.com/api/issues?projectId=project-agent-foundation&status=ready&includeDependencyGraph=true" \
  -b "buildr_plannr_session=..."

Task search response

json
{
  "data": {
    "issues": [
      {
        "id": "item-models",
        "title": "Define agent-first work item models",
        "status": "ready",
        "priority": "high",
        "agent": { "assignedAgentId": "agent-planner", "readiness": "ready" }
      }
    ],
    "dependencyGraph": {
      "edges": [{ "sourceIssueId": "item-imports", "targetIssueId": "item-models" }]
    }
  }
}

Errors

401 unauthorized

Pagination

Use status, priority, label, milestoneId, assignedAgentId, sort, and direction to keep responses bounded. Cursor pagination is planned for remote persistence.

Idempotency

No idempotency key required.

POST/api/issues/bulk-update

Previews or applies the same status, priority, labels, milestone, due date, estimate, or agent patch across a bounded task set.

Workspace session

Bulk update tasks

bash
curl -X POST https://app.buildr.example.com/api/issues/bulk-update \
  -b "buildr_plannr_session=..." \
  -H "content-type: application/json" \
  -d '{"issueIds":["item-models","item-verify"],"mode":"preview","patch":{"status":"in-review","priority":"urgent"}}'

Bulk update response

json
{
  "data": {
    "plan": {
      "requestedCount": 2,
      "targetCount": 2,
      "skippedCount": 0,
      "changedFieldLabels": ["Status", "Priority"]
    },
    "updatedIssues": [],
    "activity": []
  }
}

Errors

400 invalid-input, 401 unauthorized, 404 not-found

Pagination

Not paginated.

Idempotency

Preview mode never mutates data. Apply mode preflights all target updates before changing any task.

PATCH/api/issues/{issueId}/task-contract

Updates the clear task brief that agents use for goals, constraints, expected output, verification, permissions, and escalation. The path remains task-contract for API compatibility.

Agent API token

Update task contract

bash
curl -X PATCH https://app.buildr.example.com/api/issues/item-models/task-contract \
  -H "authorization: Bearer buildr_live_..." \
  -H "content-type: application/json" \
  -d '{"agent":{"instructions":{"objective":"Run the regression flow and attach proof."}}}'

Task contract response

json
{
  "data": {
    "issue": { "id": "item-models", "status": "ready" },
    "taskContract": {
      "issueId": "item-models",
      "goal": "Run the regression flow and attach proof.",
      "completeness": { "ready": true, "score": 100 }
    }
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden, 404 not-found

Pagination

Not paginated.

Idempotency

PATCH can be retried with the same clear task brief fields. Activity proof records the resulting issue change.

Features API

Feature planning is represented through program-level initiatives, projects, milestones, labels, parent issues, and filtered issue queries.

4 endpoints
  • Program records group strategic initiatives inside a workspace.
  • Initiative records group related projects and preserve target dates, owners, status, goals, files, and docs.
  • Feature-like records are grouped by initiativeId, milestoneId, parent issue, project goal, and feature labels.
  • Imports and exports preserve feature grouping through project, milestone, label, and dependency fields.
GET/api/programs?workspaceId=workspace-buildr

Lists workspace programs that group strategic initiatives for agent-readable planning rollups.

Workspace session

List programs

bash
curl "https://app.buildr.example.com/api/programs?workspaceId=workspace-buildr" \
  -b "buildr_plannr_session=..."

Program response

json
{
  "data": [
    {
      "id": "program-buildr-plannr-launch",
      "workspaceId": "workspace-buildr",
      "name": "Buildr Plannr launch program",
      "status": "active",
      "ownerId": "user-damien"
    }
  ]
}

Errors

401 unauthorized

Pagination

Programs are workspace-scoped and can be filtered by workspaceId, status, and q.

Idempotency

No idempotency key required.

GET/api/initiatives?programId=program-buildr-plannr-launch

Lists initiatives inside a program so integrations can group related projects under a strategic objective.

Workspace session

List initiatives

bash
curl "https://app.buildr.example.com/api/initiatives?programId=program-buildr-plannr-launch" \
  -b "buildr_plannr_session=..."

Initiative response

json
{
  "data": [
    {
      "id": "initiative-agent-foundation",
      "workspaceId": "workspace-buildr",
      "programId": "program-buildr-plannr-launch",
      "name": "Agent planning foundation",
      "status": "active"
    }
  ]
}

Errors

401 unauthorized, 404 not-found

Pagination

Initiatives are bounded by workspaceId, programId, status, and q filters.

Idempotency

No idempotency key required.

GET/api/issues?label=feature&includeDependencyGraph=true

Lists feature-labeled issues and their dependencies so integrations can synchronize feature groupings.

Workspace session

List features

bash
curl "https://app.buildr.example.com/api/issues?label=feature&includeDependencyGraph=true" \
  -b "buildr_plannr_session=..."

Feature grouping response

json
{
  "data": {
    "issues": [
      {
        "id": "item-feature-imports",
        "title": "Bulk import/export feature",
        "labels": ["feature", "import-export"],
        "milestoneId": "milestone-data-portability"
      }
    ],
    "dependencyGraph": { "edges": [] }
  }
}

Errors

401 unauthorized

Pagination

Filter by projectId, milestoneId, label, status, and q to sync one feature area at a time.

Idempotency

No idempotency key required.

GET/api/milestones?projectId=project-agent-foundation

Lists milestones that integrations can treat as release slices or feature group containers.

Workspace session

List milestones

bash
curl "https://app.buildr.example.com/api/milestones?projectId=project-agent-foundation" \
  -b "buildr_plannr_session=..."

Milestone response

json
{
  "data": [
    {
      "id": "milestone-domain",
      "projectId": "project-agent-foundation",
      "name": "Domain model",
      "status": "active",
      "targetDate": "2026-07-01"
    }
  ]
}

Errors

401 unauthorized, 404 not-found

Pagination

Milestones are scoped by projectId and currently returned as one bounded list per project.

Idempotency

No idempotency key required.

Agents API

Agent endpoints let scoped agents discover ready work, claim exactly one task, retrieve files and docs, post status, attach proof, request approvals, and check run quota.

3 endpoints
  • Agent token scope and assigned agent ID decide which tasks are visible.
  • Claims expire and cannot bypass task readiness, dependencies, allowed-action scopes, or plan run limits.
  • MCP ready-work discovery responses include handoffReadiness, queueSummary, ranked claimQueue entries, and per-item agentClaimQueue metadata so clients can choose the safest next task without reverse-engineering workspace rules.
  • Remote MCP clients can call get_client_bootstrap first to fetch endpoint, auth header, config snippet, minimum scopes, safe first calls, smoke steps, and write-gate rules for Codex, Claude Code, Cursor, Cowork, or generic clients.
  • Remote MCP clients can call get_agent_preflight to receive firstSessionDecision: track work and invite admins can start, but agent writes wait until claimable work has no critical reminders and the owner-approved write scope is clear.
  • Remote MCP clients must call get_workspace_customization before write-capable work and read the Cards/List/Tags/Swimlanes viewModes, viewPresets, adminSetupPath, rulesCenter, evidencePolicy, and handoffPacket so view choice, access, workflow, health rules, agent boundaries, and commercial controls are honored in the admin-approved order.
  • Remote MCP clients should prefer task-named tools: search_tasks, create_task, update_task_status, list_task_reminders, get_task_contract, update_task_contract, and get_context_pack. The legacy tool names remain for compatibility, but new copy should describe clear briefs plus files and docs.
  • search_tasks returns taskHealth on each result with expected completion date state, logged and estimated minutes, active reminders, blocksAgentClaim, firstReminder, safeNextActions, and agentGuidance so clients can triage before claiming or mutating work.
  • list_task_reminders returns safeNextActions for each warning; missing-date tasks expose both safe paths: set an expected date for work that should keep moving, or call update_task_status to move intentionally unscheduled work to Blocked with a reason.
  • When a follow-up has no due date yet, create_task accepts blockedReason so the task is visible, tagged blocked, and kept out of ready queues until a human clears the blocker.
  • Legacy issue-named MCP tools remain listed for older clients and map to the same guarded task mutations.
  • Remote MCP clients can use the same scoped agent token at /api/mcp to discover tools, fetch a client bootstrap packet, run one safe agent preflight with handoff readiness, fetch source-backed market standards, inspect launch-readiness proof blockers and buyer-friction blockers, search the deterministic knowledgebase, inspect task reminders, fetch workspace customization, create scoped follow-up tasks, fetch and update clear task briefs, fetch files and docs, claim work, post lifecycle status, cancel/release claims, move tasks, add comments, log time, submit proof, and request approvals.
POST/api/mcp

Serves the remote MCP JSON-RPC endpoint for tool discovery, client bootstrap packets, agent preflight, handoff readiness, source-backed market standards, launch-readiness proof blockers, buyer-friction blockers, static knowledgebase search, task reminders, workspace customization, ready work, task search, scoped task creation, clear task brief reads and updates, files and docs, claim leases, agent status posts, cancellation/release, comments, time logging, proof, and approval requests.

Agent API token

Remote MCP tools/list

bash
curl -X POST https://app.buildr.example.com/api/mcp \
  -H "authorization: Bearer buildr_live_..." \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":"tools","method":"tools/list"}'

Remote MCP tools response

json
{
  "jsonrpc": "2.0",
  "id": "tools",
  "result": {
    "tools": [
      { "name": "buildr_plannr.get_client_bootstrap" },
      { "name": "buildr_plannr.get_workspace_customization" },
      { "name": "buildr_plannr.get_agent_preflight" },
      { "name": "buildr_plannr.get_market_standards" },
      { "name": "buildr_plannr.get_launch_readiness" },
      { "name": "buildr_plannr.search_knowledgebase" },
      { "name": "buildr_plannr.list_task_reminders" },
      { "name": "buildr_plannr.list_ready_work" },
      { "name": "buildr_plannr.search_tasks" },
      { "name": "buildr_plannr.create_task" },
      { "name": "buildr_plannr.get_task_contract" },
      { "name": "buildr_plannr.update_task_contract" },
      { "name": "buildr_plannr.get_context_pack" },
      { "name": "buildr_plannr.claim_work" },
      { "name": "buildr_plannr.post_status" },
      { "name": "buildr_plannr.cancel_work" },
      { "name": "buildr_plannr.update_task_status" },
      { "name": "buildr_plannr.add_comment" },
      { "name": "buildr_plannr.log_time" },
      { "name": "buildr_plannr.add_evidence" },
      { "name": "buildr_plannr.request_approval" },
      { "name": "buildr_plannr.list_issue_reminders" },
      { "name": "buildr_plannr.search_issues" },
      { "name": "buildr_plannr.create_issue" },
      { "name": "buildr_plannr.update_issue_status" }
    ]
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden

Pagination

Not paginated.

Idempotency

Read-only MCP calls are safe to retry. Call get_agent_preflight first and read firstSessionDecision before any write-capable flow. Then call get_workspace_customization and cache the Cards/List/Tags/Swimlanes viewModes, viewPresets, adminSetupPath, rulesCenter, evidencePolicy, and handoffPacket for the current task run. Call search_tasks and inspect taskHealth.blocksAgentClaim, firstReminder, and safeNextActions before claiming or mutating any task. Call list_task_reminders and use safeNextActions before claiming work with missing dates, stale updates, missing time, or overdue dates. Task-named write aliases use the same guarded mutation path as the legacy issue-named tools. Writes require the legacy issues:write scope plus agents:execute and should only be retried when the client can tolerate duplicate comments or time entries.

GET/api/agents/ready-work

Lists ready tasks the authenticated agent token can see.

Agent API token

List ready work

bash
curl https://app.buildr.example.com/api/agents/ready-work \
  -H "authorization: Bearer buildr_live_..."

Ready work response

json
{
  "data": [
    {
      "id": "item-models",
      "title": "Define agent-first work item models",
      "status": "ready",
      "agent": { "assignedAgentId": "agent-planner", "readiness": "ready" },
      "agentClaimQueue": {
        "state": "claimable",
        "quotaState": "within-run-budget",
        "nextAction": "Agent can claim this work now.",
        "doneEvidence": { "completed": 2, "total": 6 }
      }
    }
  ]
}

Errors

401 unauthorized, 403 forbidden

Pagination

Ready work is filtered by the token workspace and agent assignment. Use separate tokens per agent role.

Idempotency

No idempotency key required.

POST/api/agents/claim

Claims one ready issue, meters an agent run, and moves ready work into progress.

Agent API token

Claim work

bash
curl -X POST https://app.buildr.example.com/api/agents/claim \
  -H "authorization: Bearer buildr_live_..." \
  -H "content-type: application/json" \
  -H "idempotency-key: claim-item-models-2026-05-22" \
  -d '{"issueId":"item-models"}'

Claim response

json
{
  "data": {
    "claim": {
      "issueId": "item-models",
      "agentId": "agent-planner",
      "expiresAt": "2026-05-22T14:00:00.000Z"
    },
    "issue": { "id": "item-models", "status": "in-progress" },
    "metering": { "allowed": true }
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden, 409 work-already-claimed

Pagination

Not paginated.

Idempotency

Send an idempotency-key for client retry correlation. The server prevents duplicate active claims by issue ID.

Imports API

Import endpoints preview, validate, redact, and commit JSON issue imports with plan-aware quota impact, progress, and recovery metadata.

2 endpoints
  • Preview records include creates, updates, conflicts, errors, quotaImpact, artifact, progress, recovery, and idempotencyKey.
  • JSON imports accept the current import schema envelope, compatible buildr-plannr export envelopes, and legacy bare issue arrays; unknown future schemaVersion values block preview before row validation.
  • Progress records expose percentComplete, processedRows, completedRows, blockedRows, activeStep, and checkpoint statuses without raw source rows.
  • History responses are redacted and omit raw source rows while preserving progress and recovery metadata.
POST/api/imports/preview

Builds a dry-run preview for JSON issue imports before any workspace data is mutated.

Workspace session

Preview import

bash
curl -X POST https://app.buildr.example.com/api/imports/preview \
  -H "content-type: application/json" \
  -H "idempotency-key: import-2026-05-22-a" \
  -b "buildr_plannr_session=..." \
  -d '{"plan":"pro","format":"json","payload":{"schemaId":"buildr-plannr.issue-import","schemaVersion":"2026-05-23.issue-import.v1","issues":[{"id":"item-imported","workspaceId":"workspace-buildr","projectId":"project-agent-foundation","title":"Imported issue"}]}}'

Import preview response

json
{
  "data": {
    "id": "import-preview-123",
    "idempotencyKey": "import-2026-05-22-a",
    "status": "ready",
    "source": { "schema": { "schemaVersion": "2026-05-23.issue-import.v1", "status": "current" } },
    "summary": { "totalRows": 1, "creates": 1, "updates": 0, "conflicts": 0, "errors": 0, "quotaExceeded": false },
    "progress": { "status": "ready", "activeStep": "commit-applied", "percentComplete": 100, "processedRows": 1, "blockedRows": 0 },
    "recovery": { "recoverable": true, "idempotencyKey": "import-2026-05-22-a" }
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden

Pagination

Not paginated.

Idempotency

Required for reliable retries. Reusing the same idempotency-key returns the existing preview metadata.

POST/api/imports/commit

Commits an unexpired, unblocked import preview.

Workspace session

Commit import

bash
curl -X POST https://app.buildr.example.com/api/imports/commit \
  -H "content-type: application/json" \
  -H "idempotency-key: import-2026-05-22-a-commit" \
  -b "buildr_plannr_session=..." \
  -d '{"previewId":"import-preview-123"}'

Import commit response

json
{
  "data": {
    "id": "import-commit-123",
    "previewId": "import-preview-123",
    "status": "committed",
    "summary": { "created": 1, "updated": 0, "skipped": 0, "totalOperations": 1 },
    "errors": []
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden, 404 not-found

Pagination

Not paginated.

Idempotency

Required for commit retries. A preview can be committed once, and retries return the committed operation metadata.

Exports API

Export endpoints produce plan-gated issue artifacts and redacted export history for backup, migration, and compliance workflows.

2 endpoints
  • Exports include schema version, created time, requested format, filters, hash metadata, retention expectations, and matching audit event IDs.
  • Audit events store export request, denial, and artifact metadata without issue bodies, issue titles, agent instructions, or raw filter identifiers.
  • Allowed formats depend on the active plan.
GET/api/issues/export?plan=hobbyist&format=json&workspaceSlug=buildr-plannr

Exports issue data for entitled plans in JSON, CSV, Markdown, or backup formats.

Workspace session

Export issues

bash
curl "https://app.buildr.example.com/api/issues/export?plan=hobbyist&format=json&workspaceSlug=buildr-plannr" \
  -b "buildr_plannr_session=..."

Issue export response

json
{
  "exportedAt": "2026-05-22T13:00:00.000Z",
  "issues": [
    {
      "id": "item-models",
      "title": "Define agent-first work item models",
      "status": "ready"
    }
  ]
}

Errors

401 unauthorized, 403 not-entitled

Pagination

Use workspaceSlug and filters to keep exported artifacts small. Large backup exports should run asynchronously in a future version.

Idempotency

No idempotency key required.

GET/api/issues/export/history

Lists redacted export artifacts and retention metadata.

Workspace session

Export history

bash
curl https://app.buildr.example.com/api/issues/export/history \
  -b "buildr_plannr_session=..."

Export history response

json
{
  "data": {
    "entries": [
      {
        "id": "export-123",
        "format": "json",
        "redacted": true,
        "retentionDays": 30
      }
    ]
  }
}

Errors

401 unauthorized

Pagination

History responses should be filtered by workspace and retained artifact metadata. Cursor pagination is planned with remote persistence.

Idempotency

No idempotency key required.

Audit API

Audit and diagnostics endpoints expose redacted operational proof for admins without returning raw tokens, secrets, payment data, or private issue payloads.

1 endpoints
  • Audit events capture authentication denials, agent token decisions, workspace access, imports, exports, status changes, proof, and approval requests.
  • Diagnostics combine audit summaries with environment readiness, product launch proof readiness, and redacted operational state.
GET/api/admin/diagnostics

Returns redacted diagnostics, audit summaries, implementation readiness, launch proof blockers, and runtime readiness signals for workspace admins.

Admin session

Get diagnostics

bash
curl https://app.buildr.example.com/api/admin/diagnostics \
  -b "buildr_plannr_session=..."

Diagnostics response

json
{
  "data": {
    "generatedAt": "2026-05-22T13:00:00.000Z",
    "audit": {
      "totalEvents": 42,
      "recentDeniedEvents": 2
    },
    "productReadiness": {
      "implementation": {
        "completionPercent": 100,
        "verifiedCount": 10
      },
      "launchProof": {
        "readyForPublicLaunch": false,
        "nextProof": {
          "id": "beta-activation-walkthrough",
          "nextAction": "Capture beta activation walkthrough proof before public launch."
        },
        "summary": {
          "publicLaunchBlockerCount": 4,
          "proofPacketCount": 6
        }
      }
    },
    "redacted": true
  }
}

Errors

401 unauthorized, 403 forbidden

Pagination

Diagnostics are summarized. Dedicated audit export pagination is planned for enterprise compliance exports.

Idempotency

No idempotency key required.

Rate limits

API access follows plan entitlements and scoped token limits.

PlanRequests/minBurstScopesNote
freeDisabledDisabledNoneAPI access disabled.
beginner60120issues:read, projects:read, agents:readAPI access enabled.
hobbyist180360issues:read, issues:write, projects:read, projects:write, agents:readAPI access enabled.
pro6001200issues:read, issues:write, projects:read, projects:write, agents:read, agents:execute, billing:readAPI access enabled.
enterprise20004000issues:read, issues:write, projects:read, projects:write, agents:read, agents:execute, billing:read, adminAPI access enabled.

Error shape

API errors return { error: { code, message } }. Quota errors may also include a redacted quota object.

400 invalid-input

Required identifiers, JSON payloads, or enum values are missing or malformed.

401 unauthorized

Session cookies or agent API token are missing, invalid, revoked, or disabled.

403 forbidden

The authenticated principal or API token lacks the required workspace action or scope.

404 not-found

The requested workspace, project, milestone, issue, preview, API key, or agent record does not exist.

409 work-already-claimed

The mutation conflicts with current workflow state, such as an active agent claim.

403 quota-exceeded

Plan-level agent runs, imports, exports, storage, or API usage limits are exhausted.

429 rate-limited

The token exceeded its requestsPerMinute or burst limit.

Pagination rules

Filter first

Use workspaceId, projectId, milestoneId, status, priority, label, assignedAgentId, and q before requesting broad issue or project lists.

Cursor-ready responses

Current local responses are small and unpaginated; remote persistence will add limit and cursor while preserving the response envelope.

Async exports

Large backup exports should move to an asynchronous job with history metadata, hash, retention, and retry-safe polling.

Idempotency rules

Import previews require idempotency keys

Send idempotency-key on /api/imports/preview so dry runs can be retried without duplicate preview artifacts.

Import commits require a separate key

Use a distinct idempotency-key when committing a preview. The preview and commit are separate operations.

Agent claims are state-guarded

Claim requests should include idempotency-key for client correlation; the server prevents duplicate active claims by issue ID.

PATCH retries are deterministic

Project, workspace, issue, and task contract PATCH calls can be retried with the same payload because unchanged fields are returned as-is.

Need help?

API support starts with request IDs, redacted examples, token scopes, plan limits, and affected workspace IDs.

Do not paste raw API tokens, Cognito cookies, Stripe secrets, or customer issue content into support requests.

Open API support