Atoll API

Base URL: https://atollhq.com

How Atoll Works

Atoll connects strategy to execution through a reasoning chain:

Goals (directional objectives with deadlines)
  → KPIs (live metrics — manual, webhook, or API-fed)
    → Initiatives (bets expected to move specific KPIs)
      → Milestones + Issues (execution work)

This means an agent can reason: "We're off pace on paying_customers → the Content Pipeline initiative should drive signups but has stalled issues → unblocking those is the highest-leverage action right now."

Agents and integrations use normal org-scoped API keys. Their permissions come from the Atoll member or integration that owns the key.

Safety Rules

• Only call Atoll when the user asks for Atoll work or when the current task clearly depends on Atoll data.
• Treat $ATOLL_API_KEY as secret. Never print it, store it in files, send it to any host except https://atollhq.com, or include it in comments or issues.
• Default to read-only requests until the user asks to create or update records.
• Before destructive actions, confirm with the user. Prefer archive endpoints over permanent delete when removing issues.
• Do not run a background heartbeat loop unless the user explicitly asks for a recurring check or automation.

Authentication

All requests require: Authorization: Bearer sk_atoll_<key>

API keys are generated in Settings > Members > Add Agent (for agents) or Settings > Members > Create API Key (for integrations). Each key is scoped to one org. Store both values as env vars:

export ATOLL_API_KEY="sk_atoll_..."
export ATOLL_ORG_ID="..."          # UUID of the org the key belongs to

Sanity check — exercises the org-scoped issues endpoint, not just /api/auth/me:

: "${ATOLL_API_KEY:?missing}" "${ATOLL_ORG_ID:?missing}" && \
  curl -sS -o /dev/null -w "HTTP:%{http_code}\n" \
    "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=1" \
    -H "Authorization: Bearer $ATOLL_API_KEY"
# Expect: HTTP:200

If $ATOLL_ORG_ID is empty, the URL collapses to /api/orgs//issues which 308-redirects to a non-existent route and returns Unauthorized — a misleading symptom that looks like an auth failure. GET /api/auth/me alone cannot catch this since it doesn't depend on $ATOLL_ORG_ID. Always guard both vars.

Quick Start — CLI (recommended)

Install globally or use via npx:

npm install -g @atollhq/cli   # or: npx @atollhq/cli ...

Configure once:

atoll auth login --key sk_atoll_...
atoll config set-org my-org

For machines or agents that need multiple credentials, use auth profiles:

atoll auth login --profile agent-a --key sk_atoll_... --org acme
atoll auth login --profile agent-b --key sk_atoll_... --org client
atoll auth profiles
atoll auth use agent-a

# Run one command as a specific profile
atoll --profile agent-b issue list

Common commands:

# Agent orientation
atoll heartbeat
atoll heartbeat --signals-only
atoll heartbeat --severity critical
atoll heartbeat --json
atoll agent-context

# List tasks
atoll issue list --json
atoll issue list --status todo --priority 1 --limit 25

# View a task
atoll issue get ATOLL-42
atoll issue view ATOLL-42   # alias kept for humans

# Create a task
atoll issue create --title "Fix login bug" --status todo --priority 1

# Update a task
atoll issue update ATOLL-42 --status in_progress

# Assign a task
atoll issue assign ATOLL-42 --to <user-id>
atoll issue assign ATOLL-42 --to self

# Comments
atoll comment add ATOLL-42 --body "Working on this now"

# Safe removal
atoll issue archive ATOLL-42
atoll issue unarchive ATOLL-42
atoll issue delete ATOLL-42 --dry-run
atoll issue delete ATOLL-42 --force

# Report friction to Atoll maintainers
atoll feedback "The status error should list custom board statuses"

# Projects & milestones
atoll project list
atoll milestone list --project <project-id>

Prefer the CLI for routine task operations, heartbeat checks, comments, and feedback. Use direct API calls when the CLI does not expose the needed endpoint yet.

CLI JSON conventions:

• Use --json for machine-readable output.
• List commands return { resource, items, total, limit, offset, nextOffset, truncated, hint }.
• Diagnostics and errors go to stderr.
• atoll agent-context returns a versioned command/flag manifest and available profile context.

Quick Start — API (for advanced use)

All CLI commands map to REST endpoints. Use the API directly when the CLI doesn't cover a specific operation.

# Prereq: both env vars exported (see Authentication above)
atoll() {
  : "${ATOLL_API_KEY:?ATOLL_API_KEY not set}"
  : "${ATOLL_ORG_ID:?ATOLL_ORG_ID not set}"
  curl -s -H "Authorization: Bearer $ATOLL_API_KEY" \
       -H "Content-Type: application/json" \
       "https://atollhq.com$1" "${@:2}"
}

atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"

The Heartbeat Loop

The primary pattern for autonomous agents. Prefer atoll heartbeat --json when the CLI is available; it wraps GET /api/orgs/{id}/heartbeat and returns the same computed briefing:

• Goal status with days remaining
• KPI pace: pace_needed vs pace_actual, trend (accelerating/decelerating/flat), staleness
• Initiative progress: total/completed/stalled/blocked issue counts, expected KPI impacts
• Assigned work for this agent
• Signals sorted by severity — the agent's prioritized to-do list

Signal types: kpi_off_pace, kpi_stale, issue_stale, issue_blocked, milestone_overdue, initiative_stalled, webhook_failing. Severity: info, warning, critical.

Useful CLI forms:

atoll heartbeat
atoll heartbeat --signals-only
atoll heartbeat --severity critical
atoll heartbeat --json

The agent loop:

1. Call heartbeat
2. Read signals (highest severity first)
3. Reason about highest-leverage action given KPI pace and initiative state
4. Execute (unblock issues, update KPIs, create work, report progress)
5. Repeat

Other Common Workflows

Pick up and complete a task

atoll heartbeat --signals-only                        # orient first
atoll issue list --status todo --assignee self --json # find assigned work
atoll issue update ATOLL-42 --status in_progress      # start work
atoll comment add ATOLL-42 --body "Progress update…"  # report progress
atoll issue update ATOLL-42 --status done              # complete

Set up the strategy chain

1. POST /api/orgs/{id}/goals -- create goal with target_date
2. POST /api/orgs/{id}/kpis -- attach KPI with goal_id, target_value, target_direction
3. POST /api/orgs/{id}/kpis/{kpiId}/snapshots -- record measurement (auto-updates current_value)
4. POST /api/orgs/{id}/initiatives -- create initiative linked to goal
5. POST /api/orgs/{id}/initiatives/{id}/kpi-impacts -- declare expected KPI impact
6. Link issues and milestones to the initiative

Every KPI snapshot can be attributed to an initiative or issue, building a record of what actually moved the numbers.

Bulk create tasks from a plan

POST /api/orgs/{id}/issues/bulk with { "issues": [{...}, ...] } (max 50).

Billing and plan limits

Owners/admins can read billing state with GET /api/orgs/{id}/billing and start Stripe checkout with POST /api/orgs/{id}/billing/checkout using { "plan": "starter" } or { "plan": "team" }.

Creation endpoints can return 402 with code: "PLAN_LIMIT_REACHED" when an org reaches limits for humans, agents/integrations, active projects, or active issues.

API Reference

Full endpoint tables and field schemas:

• references/api-endpoints.md -- all endpoints organized by resource
• references/api-fields.md -- request/response schemas, field definitions, enums

Key resources

All endpoints are under /api/orgs/{orgId}/....

† DELETE /issues/{id} requires owner or admin role — any caller without that role (including member-role agents) gets 403. If you just need to remove a task, use POST /api/orgs/{orgId}/issues/{issueId}/archive (soft delete, no role gate); reverse with DELETE on the same path (unarchive). In the CLI, prefer atoll issue archive <id>. Permanent atoll issue delete <id> requires --force and supports --dry-run.

Quick enum reference

• Task status: backlog, todo, in_progress, done, cancelled (custom per project)
• Priority: 0 urgent, 1 high, 2 medium, 3 low
• Goal status: active, achieved, missed, paused, cancelled
• Initiative status: proposed, active, completed, paused, cancelled
• KPI direction: increase, decrease, maintain
• Member role: owner, admin, member, guest

Platform Feedback

Report bugs or request features for the Atoll platform itself. This sends feedback to the Atoll team's internal board — not to your org.

curl -X POST https://atollhq.com/api/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bug",
    "description": "The /issues endpoint returns 500 when filtering by milestoneId and status together",
    "userEmail": "agent@example.com",
    "userName": "My Agent"
  }'

No authentication required. Use this when you encounter unexpected API errors, missing functionality, or have suggestions for the platform.

The CLI can record the same feedback locally, and optionally submit upstream:

atoll feedback "The /issues endpoint returns 500 when filtering by milestoneId and status together"
atoll feedback --send "heartbeat should emit issue_blocked signals directly"
atoll feedback list --json

Notes

• Request bodies accept camelCase; responses use snake_case
• Descriptions and comments support Markdown
• All timestamps are ISO 8601 UTC
• Board statuses are customizable per project -- query /board-columns for available values
• API changes appear in real-time on the web board
• List endpoints support limit (default 25, max 100) and offset pagination