bbuildr-plannr
Log inStart 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

17

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.

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

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 milestones, labels, parent issues, and filtered issue queries until a dedicated feature object ships.

2 endpoints
  • Feature-like records are grouped by milestoneId, parent issue, project goal, and feature labels.
  • Imports and exports preserve feature grouping through project, milestone, label, and dependency fields.
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.

2 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.
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" }
    }
  ]
}

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 and recovery metadata.

2 endpoints
  • Preview records include creates, updates, conflicts, errors, quotaImpact, artifact, recovery, and idempotencyKey.
  • History responses are redacted and omit raw source rows.
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":{"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",
    "summary": { "totalRows": 1, "creates": 1, "updates": 0, "conflicts": 0, "errors": 0, "quotaExceeded": false },
    "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, and retention expectations.
  • 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