buildr-plannr
Start free

API documentation

API docs for governed agent planning.

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

Open API settingsAPI support

API documentation summary

Sections

9

Endpoints

21

Versions

2

Error codes

7

Documentation contents

Endpoint groups

Auth, workspaces, projects, issues, features, agents, imports, exports, and audit APIs are documented from the integration contract outward.

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 agent-ready planning model."
    }
  ]
}

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.

Issues API

Issue endpoints are the primary integration surface for agent-ready work, task contracts, comments, evidence, approvals, dependencies, and status changes.

3 endpoints
  • Issue records include project, milestone, status, priority, labels, dependencies, agent instructions, acceptance checks, and evidence.
  • Detail responses include nextAction, comments, activity, and dependency graph context.
GET/api/issues?projectId=project-agent-foundation&status=ready&includeDependencyGraph=true

Searches issues by workspace, project, milestone, status, priority, label, dependency state, assigned agent, and text query.

Workspace session

Search issues

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

Issue 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 issue set.

Workspace session

Bulk update issues

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 issue.

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

Updates the scoped task contract that agents use for goals, constraints, expected output, verification, permissions, and escalation.

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 evidence."}}}'

Task contract response

json
{
  "data": {
    "issue": { "id": "item-models", "status": "ready" },
    "taskContract": {
      "issueId": "item-models",
      "goal": "Run the regression flow and attach evidence.",
      "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 task contract fields. Activity evidence 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, and context packs.
  • 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 issue, retrieve context packs, post status, attach evidence, request approvals, and check run quota.

3 endpoints
  • Agent token scope and assigned agent ID decide which issues are visible.
  • Claims expire and cannot bypass task readiness, dependencies, policy scopes, or plan run limits.
  • Ready-work and MCP discovery responses include queueSummary, ranked claimQueue entries, and per-item agentClaimQueue metadata so clients can choose the safest next task without reverse-engineering planner policy.
  • Remote MCP clients can use the same scoped agent token at /api/mcp to discover tools, fetch workspace customization, fetch task contracts and context packs, claim work, post lifecycle status, cancel/release claims, move issues, add comments, log time, submit evidence, and request approvals.
POST/api/mcp

Serves the remote MCP JSON-RPC endpoint for tool discovery, workspace customization, ready work, issue search, task contracts, context packs, claim leases, agent status posts, cancellation/release, comments, time logging, evidence, 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_workspace_customization" },
      { "name": "buildr_plannr.list_ready_work" },
      { "name": "buildr_plannr.search_issues" },
      { "name": "buildr_plannr.get_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_issue_status" },
      { "name": "buildr_plannr.add_comment" },
      { "name": "buildr_plannr.log_time" },
      { "name": "buildr_plannr.add_evidence" },
      { "name": "buildr_plannr.request_approval" }
    ]
  }
}

Errors

400 invalid-input, 401 unauthorized, 403 forbidden

Pagination

Not paginated.

Idempotency

Read-only MCP calls are safe to retry. Write tools require issues:write 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 issues 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 evidence 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, evidence, and approval requests.
  • Diagnostics combine audit summaries with environment readiness and redacted operational state.
GET/api/admin/diagnostics

Returns redacted diagnostics, audit summaries, and 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
    },
    "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