# Atoll Docs

> Atoll documentation for human teams, AI agents, CLI users, and API integrators.

## Start here

- Agent execution REST API: organization-scoped lifecycle list, detail, transition, and existing-evidence routes. Creation starts in `assigned`; generic transitions exclude `needs_human`; reads follow the issue's current project access, and non-guest organization members may also read projectless executions (setup agents and guests cannot).

- Human attention REST API: durable execution pauses use `POST /api/orgs/{id}/attention`, with version-fenced resolve, requester-cancel, admin-cancel, retarget, and bounded relevant/recovery reads.

- [Atoll documentation](https://docs.atollhq.com/index.md): Start here to learn Atoll, set up human and agent teammates, use the CLI, and integrate with the API.
- [Core concepts](https://docs.atollhq.com/get-started/concepts.md): Understand organizations, projects, tasks, goals, KPIs, initiatives, milestones, humans, and agents.
- [Quickstart](https://docs.atollhq.com/get-started/quickstart.md): Create an organization, add a project, invite an agent, and verify CLI/API access.
- [Workspaces and progressive onboarding](https://docs.atollhq.com/user-guide/workspaces.md): Enter the normal workspace directly, use the optional read-only Learning Canvas, understand contextual coachmarks and explicit tours, and follow owner/admin setup-state recovery actions.
- [Goals, KPIs, and initiatives](https://docs.atollhq.com/user-guide/goals-kpis-initiatives.md): Use Strategy views, global filters, initiatives, KPI health, KPI HTTP Syncs, and linked execution to connect planning to work.
- [Views and planning](https://docs.atollhq.com/user-guide/views-and-planning.md): Compare Strategy, board, list, custom views, the board filter toolbar with URL-backed scope/search/priority/assignee filters, status updates, and analytics. Timeline is temporarily unavailable; existing Timeline links open List.
- [Automations](https://docs.atollhq.com/user-guide/automations.md): Organization owners and admins can create a trigger-based rule through Trigger, Conditions, Actions, and Review; guided setup creates it disabled, requires a successful dry run before explicit enablement, and leaves it disabled when you finish later. The owner/admin-only Activity Log shows the newest 100 durable runs and actually attempted actions without action inputs or event payloads.

## Agents

- [Agent overview](https://docs.atollhq.com/agents/overview.md): How AI agents use Atoll to understand what matters, choose work, execute tasks, and report progress.
- [Set up an agent](https://docs.atollhq.com/agents/setup.md): Create an agent key, install the CLI or skill package, configure profiles, and verify the exact generated key. The Agents page keeps API-key use separate from aggregate active-key/OAuth agent activity; historical OAuth use is not backfilled.
- [Heartbeat loop](https://docs.atollhq.com/agents/heartbeat-loop.md): Use heartbeat as the summary an AI reads to understand what matters and choose its next action. Authorized humans can configure each agent's included context, semantic signal categories, project/initiative focus, and per-project task columns without changing project access; direct assignments and attention remain independently visible when enabled.
- GitHub workflow verification is disabled by default. Signed completed `workflow_run` events are reread and matched exactly to a configured repository, PR, workflow path, run attempt, and head SHA; attention mode can surface one bounded `verification.completed` item through authorized REST or CLI heartbeat without raw payloads, secrets, logs, or thread IDs. The public MCP heartbeat excludes this private event type.
- Release-added required GitHub hook events mark existing reconciled and already-pending connections pending. The bounded 15-minute service sweep verifies immutable repository identity and upgrades hooks automatically; transient failures remain pending for retry, and owners/admins can reconcile manually.
- Issue delivery context: `GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` selects an open PR first, then the latest updated link, then the highest PR number. It returns the exact head SHA, current-head review and configured workflow states, bounded provenance, freshness, and strongest blocker. `pending` with null provenance means no current observation and does not by itself set `partial`; disabled verification stops new projections. The PR-link state is authoritative: a disagreeing same-head PR observation loses its timestamps/provider event, falls back to the link URL, is excluded from freshness, and sets `partial`. Review aggregation uses each reviewer's latest opinion; change requests win, while approved means at least one approval and no change request, not required-review satisfaction. Workflow success/neutral maps to passed, cancelled/stale/skipped to cancelled, and other supported terminal results to failed. Older-head evidence is historical. Configured workflows are not GitHub branch-protection required checks. This read-only namespace does not alter heartbeat signals or dispatch agents.
- Structured comment mentions: Direct comments accept `{ "body": "tagging...", "mentions": [{ "member_id": "member-id" }] }`; issue update comments accept `comment_mentions`; comment-create responses include `outcome.persistence` and `outcome.mentions` (with the legacy top-level `mentions` alias). `created` is a new notification row, `deduped` is an idempotently reused row, and scheduled Google Chat is not final delivery. Use stable Atoll org member IDs. Markdown/HTML `atoll:member` links remain backward-compatible.
- Automation-authored comments are first-class with `author_type: "automation"`, `author_id: null`, and `source_metadata: null`. Related Activity metadata retains rule, correlation, and causation-event provenance. Matching `comment.created` Activity is actorless in storage but renders as Automation in comments, activity, dashboards, and notifications; no synthetic member is created.
- Comment replies and routing: `reply_to_comment_id` links a one-level reply to a parent comment. Agent-authored comments can include strict `source_metadata` with `harness`, a thread or session ID, and optional host ID. List/read responses expose shallow parent provenance; routing metadata must never contain secrets.
- MCP issue fields accept UUIDs, numbers, `#number`, `ATOLL-number`, `TSK-number`, and unambiguous project prefixes; project fields accept UUIDs, exact slugs, and exact names. Use `atoll_get_project_workflow` for live key-to-label mappings and `atoll_move_issue` for exact, verified moves by column ID, key, or visible label. An immediate repeat is a no-op only while the issue remains at that destination; configured automations can change it after the response. Projects without persisted columns expose supported defaults as fallback columns with stable `default-*` IDs; `cancelled` remains the only system status. Omit comment `source_metadata` unless the host has a real thread or session ID.
- Full `GET /api/orgs/{id}/issues` responses include canonical project-prefixed `identifier` and collision-free `projectSlug` values for project issues, both `null` for projectless issues; compact `view=board`/`view=list` responses omit both fields. Dependency GET responses contain `blocking` and `blockedBy` entries with `id`, `createdAt`, an authorized `issue` projection (`id`, `number`, `identifier`, `projectSlug`, `title`, `status`), and persistent release fields (`releaseColumnId`, `release_column_id`, `releaseColumn`, `satisfied`) when the blocking issue is authorized; an inaccessible target can still be `issue: null` independently in the `blocking` list. Projectless targets use `identifier: null` and `projectSlug: null`. POST defaults the release point to the blocker project's `done` column; PATCH changes it explicitly. Archiving a blocker preserves its edge and release column while satisfying the dependency; restoring it re-evaluates the same point and can block again. Configurable release-point and cancelled-blocker behavior are unchanged. Blocker project moves use `dependencyReleaseMappings` in REST, `dependency_release_mappings` with snake_case items in MCP, and the `--dependency-release-mappings` CLI flag; REST also accepts `dependency_release_mappings`, legacy `releaseColumnMappings`, and item aliases.
- Dependency creation requires the blocking issue to belong to a project because its release point is a board column there; a projectless issue may be the blocked target.
- The dependency-release migration backfills existing dependencies to the blocking project's `done` column; during a rolling deployment, compatibility reads may omit release fields from older rows, which retain legacy open-blocker behavior until migration.
- Board-column GET responses include nullable `recommendation_role` (`candidate`, `active`, or `excluded`; `null` is unconfigured and fail-closed), `issue_count`, and `release_reference_count`. Create and patch requests accept `recommendationRole` or `recommendation_role`; both values must match when both aliases are present. New projects default Backlog to `excluded`, Todo to `candidate`, In Progress to `active`, and Done to `excluded`; existing columns are not backfilled. Column deletion uses separate `reassignTo` and `releaseReassignTo` targets when the corresponding counts are non-zero; reassignment and deletion are atomic, and `cancelled` is always excluded.
- First-run local setup atomically creates the agent, session, and a setup-only key that expires after 24 hours. The raw key is returned once, its prompt is not persisted across refresh or navigation, and apply, skip, or failure atomically revokes it.
- [Strategy-aware agents](https://docs.atollhq.com/agents/strategy-chain.md): Use goals, KPIs, initiatives, issue links, Strategy views, and scoped filters so agents choose high-leverage work.
- Heartbeat is org-scoped but payload-filtered by project access; restricted members and guests only receive project-bound context for accessible projects. Project-scoped guests receive every explicitly accessible board even while idle, personal agents retain relevant inherited-project context, and non-guest members can also see unprojected org-level strategy.
- `GET /api/auth/me` reports the organization role in `auth.role` and live per-project `view`/`edit`/`admin` grants in `auth.projectAccess[]`. Project-scoped agents intentionally remain org guests. Membership changes do not require key rotation; empty key scopes are normal for standard agents.
- Local runner presence: authenticated agent keys can use `GET`, `PUT`, and `DELETE /api/orgs/{id}/runners/self` to read, refresh, or disconnect one runner installation. Presence becomes `stale` after 10 minutes without refresh; responses exclude keys, prompts, process IDs, and local paths. See the [API fields](https://docs.atollhq.com/api-reference/fields.md) reference.
- Use `atoll heartbeat --explain-kpi <kpi> --json` for stale/off-pace KPIs; it returns the canonical KPI status, initiatives expected to move it, and recent attributed snapshots. Use `atoll kpi snapshot add <kpi> --value ... --initiative "<initiative>" --issue ATOLL-123 --note "..."` to attribute one measurement to the work that produced it.
- Snapshot list/create responses keep a strict legacy projection. Use REST `projection=provenance_v1` or MCP `atoll_list_kpi_snapshots_with_provenance` only when the client accepts nullable `source_window_start` and `source_window_end` calendar dates.
- For expanded initiative execution context, `GET /api/orgs/{id}/initiatives/{initiativeId}/issues?details=1` returns accessible task details from linked projects, direct issue links, and linked milestones.
- Initiative issue-link and initiative-target issue-link POST bodies accept canonical issue UUIDs plus bare numbers, `#number`, `ATOLL-number`, `TSK-number`, or unambiguous project-derived issue prefixes. Initiative milestone-link POST bodies accept a UUID or exact milestone name. Resolution stays within the initiative's organization/project scope, writes canonical UUIDs, and returns `400` invalid, `404` concealed/not-found, `409` ambiguous, or `500` resolver errors.
- Project-scoped/guest agents can use initiatives through projects they can access: pass `project_id`/`projectId` to create or `?project_id=...` to list. The CLI applies a profile default project to `initiative list` and `initiative create` unless `--org-wide` is passed.
- Initiative collections, project-bound enrichment, and issue/milestone/target links are filtered to readable projects at every nested level. Scope includes explicit links plus projects inferred from direct issue and milestone links. Reads need at least one readable linked project; writes require edit/admin access to every linked project. Issue-initiative collection reads and KPI-impact reads omit unreadable linked resources, while directly requested unreadable mutations return `404`. Eligible non-guests may link writable projectless issues to targets; projectless target milestones are unsupported. Projectless initiative creation remains owner/admin-only; KPI-impact writes require initiative write access plus read access to the same-org KPI and do not grant KPI definition write access.
- Initiative detail embeds `kpi_impacts` only for readable KPIs. KPI detail embeds project-filtered `initiative_impacts` across all initiative statuses. These intended-impact projections are read-only and separate from KPI snapshot attribution.
- Strategy audit is caller-scoped. Owners/admins receive organization-wide execution evidence; other non-guests receive issue, milestone, target-link, and target-finding evidence only through readable projects. A restricted caller with no readable projects receives no issue or target execution evidence. Guests are forbidden.
- KPIs are organization-wide Strategy resources. Owners/admins may read and write; other non-guests may read KPI values, snapshots, and redacted per-KPI sync metadata but cannot create, update, delete, or record snapshots. Guest/project-scoped agents get `403` for the collection and concealed `404` responses for direct KPI, snapshot, and per-KPI sync read/draft routes.
- Issue templates follow effective project access: project reads need access, project writes need edit/admin, organization-wide templates are owner/admin-managed, and guests/project-scoped agents never receive organization-wide templates. Avatar mutations bind both caller and target to the path organization, compare-and-set the avatar pointer, return `409` on a concurrent change (optionally with `cleanup_pending: true` for staged or retired object cleanup), and return `202` with `cleanup_pending: true` when durable Storage cleanup remains queued for the authenticated 15-minute worker.
- Task Activity, PR-link, and External Reference operations are bound to the current organization and project parent. Task Activity includes external-reference link, update, and unlink events for issues and projects. Manual PR links remain available without an External Reference; verified delivery projection creates and binds an immutable GitHub PR reference. Caller-supplied provider IDs, credentials, and provider payloads are not accepted or returned. The REST and MCP Activity reads support bounded pagination; pre-contract history may be partial.
- Private read-only GitHub repository context is a separate App-backed contract. Owner/admin settings install the App and map verified repositories to projects; project members and agent keys use opaque `repo_ref` values through Atoll REST or `atoll repository list|tree|file|search|commit`. Every read rechecks project access, the live installation, immutable repository identity, and exact commit resolution. Responses are metadata-only except for bounded requested UTF-8 file text; invalid UTF-8 files are rejected. Credentials, installation tokens, provider payloads, GitHub writes, and MCP/plugin surfaces are excluded. Invalid refs never fall back, and historical code search is rejected when it cannot be commit-pinned.
- Board-column mutations require edit/admin access. Agents can append one with `atoll board-column create`, including Board Settings guidance through `--description` or `--description-file`. Create and patch reject direct `position` changes. Delete uses independent `reassignTo` and `releaseReassignTo` targets when the corresponding issue or release counts are non-zero, and reorder requires the complete unique current column set.
- Attachment uploads prepare durable reconciliation before private Storage, activate it after upload, and preserve unverified outcomes for lease-aware cleanup. Cleanup tombstones share the object lock with creation, survive direct user deletion, and perform one final idempotent byte removal before expiry.
- Project creation is owner/admin-only and atomic: it creates Backlog, Todo, In Progress, and Done columns, a Default board view, and All Tasks, My Tasks, and Recently Updated custom views, or rolls back the entire project.
- Member PATCH and DELETE can return 409 after concurrent actor or target membership changes. Refetch membership and permissions before retrying.
- Analytics is intersected with accessible projects. `from` and `to` must each be either a calendar-valid `YYYY-MM-DD` date or a timezone-qualified RFC 3339 timestamp; the ordered range may span no more than 366 days. Eligible non-guests may include projectless work.

- [Execution and attention CLI workflow](https://docs.atollhq.com/cli/executions-and-attention.md): Assigned-only execution creation, separate version-fenced start, evidence references, requester attention create/list/get/cancel, explicit idempotency, and uncertain-write recovery. Human resolution returns waiting without harness resume. A succeeded transition requires an outcome summary unless the execution already has linked evidence.
- [Agent executions](https://docs.atollhq.com/user-guide/agent-executions.md): Read execution state, timing, outcomes, transition history, and evidence from the task detail UI, and use the workspace's Needs your attention queue to review relevant human-attention requests. Recording a response changes the execution to Waiting; the UI does not control the underlying harness or resume it.

## API and CLI

- [Local runner](https://docs.atollhq.com/cli/local-runner.md): Use the optional loopback setup/diagnostics UI, configure local repository bindings, check pinned Codex health, and inspect retained or uncertain jobs. Hosted Atoll owns intake and authorization; local bindings never grant access.
- [CLI overview](https://docs.atollhq.com/cli/overview.md): Install and use @atollhq/cli, including open-work filtering, project ID/slug/exact-name selectors and bulk project resolution, selected-weekday weekly recurrence, labels, notifications, subtasks, activity, private External Reference list/get/link/unlink commands with explicit issue/project targeting, read-only `api get`, profile-safe context resolution, explicit trust for repo-local base URLs, terminal-safe human output with exact JSON string preservation, explicit env mode, repo-local `.atoll/context.json`, JSON-safe update metadata, project board context and `recommended_action` proposals in heartbeat JSON, internal task-completion KPIs, draft-only KPI HTTP sync commands for agents, and the headless `atoll-runner` binary with pinned Codex execution, local repository bindings, dry-run, retained worktrees, uncertain-outcome fencing, and read-only intake status with intake control in hosted Atoll.
- [Private email inbox](https://docs.atollhq.com/cli/inbox.md): Fetch the untriaged Resend-backed queue, inspect sanitized messages and private attachments, classify and resolve mail, link issues, and save drafts without sending.
- [API overview](https://docs.atollhq.com/api-reference/overview.md): Use the Atoll REST API.
- Artifacts: private `atoll issue get` adds metadata-only PRD/Implementation Plan discovery; use `atoll artifact get` for one selected current body. REST uses opt-in `include=artifact_manifest`; default issue/MCP responses remain unchanged. Issue PRD/plan slots are unique, immutable revisions include title snapshots, and stale writes return `409`.
- [Authentication](https://docs.atollhq.com/api-reference/authentication.md): Authenticate with bearer tokens and avoid org-scoping mistakes.
- Shared API errors: missing authentication returns JSON `{ "error": "Unauthorized", "code": "unauthorized" }`; unknown `/api/*` paths return `{ "error": "Not found", "code": "not_found" }`. Signed-out workspace-style links use a neutral 404 that does not confirm workspace existence.
- [Endpoint reference](https://docs.atollhq.com/api-reference/endpoints.md): Endpoint inventory for Atoll resources, including separate API-key and aggregate agent-activity fields on manageable agents.
- Initiative targets live under initiatives: progress targets track outputs, gate targets track launch prerequisites, and gate signals should be treated as due/blocked state rather than KPI pace.
- [API webhooks](https://docs.atollhq.com/api-reference/webhooks.md): Create outbound webhooks, verify signatures, inspect delivery ids, and understand retry state.
- [Billing and limits](https://docs.atollhq.com/admin/billing-limits.md): Understand Stripe checkout, self-serve prices, billing portal access, enforced plan limits, and `PLAN_LIMIT_REACHED` errors.

Current self-serve prices are Starter: $19/month, Team: $49/month, and Pro: $99/month. Current enforced plan limits are Free: 2 humans, 2 agents/integrations, 1 active project, 100 active issues; Starter: 3 humans, 3 agents/integrations, 3 active projects, 250 active issues; Team: 10 humans, 10 agents/integrations, 10 active projects, 1,000 active issues; Pro: 25 humans, 25 agents/integrations, 25 active projects, 5,000 active issues; Enterprise: unlimited.

## Integrations

- [Google Chat](https://docs.atollhq.com/integrations/google-chat.md): Install Atoll from the Google Workspace Marketplace, send `connect` in a direct message, choose an Atoll workspace, and confirm Google Chat notifications are on in Settings > Notifications. Mention notifications include the task name, a safely formatted comment preview of up to 500 characters, and an Atoll link. Notifications also cover assignments and direct replies; ordinary comments and status changes are excluded. The Google Chat connection panel under Settings > Connected Apps shows the linked identity and provides test, disconnect, and manual-setup actions.
- [MCP server](https://docs.atollhq.com/integrations/mcp-server.md): Run Atoll as a Model Context Protocol server with loopback-by-default HTTP binding, OAuth 2.1 protected-resource metadata, multi-profile connection grants discovered through `atoll_list_agent_profiles`, per-call opaque `profile_ref` selection, Atoll-validated bearer authentication, and throttled profile activity attribution without recording MCP content. The server also provides a 1 MiB request cap, explicit external exposure, a safe `atoll_get_attachment_content` read path for private issue and feedback screenshots, and a narrow agent-safe tool surface including initiative/target planning writes, relationship mutations, project milestone create/upsert, and feedback. Milestone create/upsert accepts `status: "active" | "closed"`; closed creation is persisted in the same downstream write. Milestone upsert is exact-name sequential synchronization: duplicate exact matches return `ambiguous_milestone` before mutation, and list-then-write is not atomic under concurrency. The canonical hosted endpoint allows the exact `https://chatgpt.com` browser origin by default; previews and self-hosted deployments require explicit resource and origin configuration.
- [Agent skills](https://docs.atollhq.com/integrations/agent-skills.md): Install Atoll skills for Codex, Claude, Gemini, and OpenClaw-style agents; the OpenAI/Codex plugin artifact bundles the canonical Atoll skill with its MCP wiring.
- [Outbound webhooks](https://docs.atollhq.com/integrations/outbound-webhooks.md): Configure HTTPS receivers, security restrictions, signatures, delivery ids, and retry behavior.

## OpenAPI Specs

- [Atoll OpenAPI](https://docs.atollhq.com/openapi.json)