Authorization: Bearer sk_atoll_... unless noted.
Organizations
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs | List your organizations |
POST | /api/orgs | Create an organization |
GET | /api/orgs/{id} | Get organization details |
PATCH | /api/orgs/{id} | Update organization |
DELETE | /api/orgs/{id} | Delete organization |
Projects
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/projects | List visible projects |
POST | /api/orgs/{id}/projects | Create project |
GET | /api/orgs/{id}/projects/{projectId} | Get project with issues |
PATCH | /api/orgs/{id}/projects/{projectId} | Update project |
DELETE | /api/orgs/{id}/projects/{projectId} | Permanently delete project and all tasks in it; requires { "confirmation": "DELETE" } |
POST | /api/orgs/{id}/projects/{projectId}/archive-by-status | Archive issues by status |
GET | /api/orgs/{id}/project-health | Latest health status per project |
Project access
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/projects/{projectId}/members | List project members |
POST | /api/orgs/{id}/projects/{projectId}/members | Add project member |
PATCH | /api/orgs/{id}/projects/{projectId}/members | Update project access |
DELETE | /api/orgs/{id}/projects/{projectId}/members?memberId=... | Remove project member |
GET | /api/orgs/{id}/projects/{projectId}/teams | List project teams |
POST | /api/orgs/{id}/projects/{projectId}/teams | Add team to project |
DELETE | /api/orgs/{id}/projects/{projectId}/teams?teamId=... | Remove team from project |
{ "memberId": "...", "accessLevel": "view" | "edit" | "admin" }. If accessLevel is omitted, Atoll defaults it to edit; invalid values return 400.
Issues
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/issues | List issues |
POST | /api/orgs/{id}/issues | Create issue |
GET | /api/orgs/{id}/issues/{issueId} | Get issue detail |
PATCH | /api/orgs/{id}/issues/{issueId} | Update issue; optional comment_body and comment_mentions also add an issue comment in the same request |
DELETE | /api/orgs/{id}/issues/{issueId} | Permanently delete issue, owner/admin only |
POST | /api/orgs/{id}/issues/{issueId}/archive | Archive issue |
DELETE | /api/orgs/{id}/issues/{issueId}/archive | Unarchive issue |
POST | /api/orgs/{id}/issues/bulk | Bulk create issues, max 50 |
GET | /api/orgs/{id}/issues/search?q=... | Search issues by title/description |
GET | /api/orgs/{id}/issues/{issueId}/activity | Issue activity feed |
GET | /api/orgs/{id}/issues/{issueId}/pr-links | Linked pull requests |
POST | /api/orgs/{id}/issues/{issueId}/pr-links | Attach a GitHub PR URL with { "url": "https://github.com/owner/repo/pull/123" } |
GET | /api/orgs/{id}/issues/{issueId}/initiatives | List initiatives linked to an issue |
POST | /api/orgs/{id}/issues/{issueId}/initiatives | Link issue to initiative with { "initiative_id": "..." } |
DELETE | /api/orgs/{id}/issues/{issueId}/initiatives/{initiativeId} | Unlink issue from initiative |
400. When GitHub metadata is available, Atoll stores the current PR title, status, canonical URL, and head SHA during attach; webhooks keep linked PR state fresh after subsequent GitHub events.
Issue list filters include status, priority, projectId, assigneeId, teamId, milestoneId, q (title and description for full issue lists), includeArchived, orderBy, orderDir, limit, offset, and the optional response shape controls below.
Compact issue views (view=board or view=list) also support board-toolbar filters: assignee (unassigned or member ID, including multi-assignee links), initiativeId, scope (mine or blocked), and q over title plus issue number.
Main list endpoints keep their legacy resource-key JSON by default. Add shape=envelope or response_shape=cli to opt into the CLI-compatible envelope: { resource, items, total, limit, offset, nextOffset, truncated, hint }.
Comments, subtasks, dependencies, labels, and attachments
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/issues/{issueId}/comments | List comments; requires access to the issue’s project |
POST | /api/orgs/{id}/issues/{issueId}/comments | Add comment with { body, mentions? }; requires write access to the issue’s project |
PATCH | /api/orgs/{id}/issues/{issueId}/comments/{commentId} | Edit comment |
DELETE | /api/orgs/{id}/issues/{issueId}/comments/{commentId} | Delete comment |
GET | /api/orgs/{id}/issues/{issueId}/subtasks | List subtasks |
POST | /api/orgs/{id}/issues/{issueId}/subtasks | Create subtask |
PATCH | /api/orgs/{id}/issues/{issueId}/subtasks/{subtaskId} | Update subtask |
DELETE | /api/orgs/{id}/issues/{issueId}/subtasks/{subtaskId} | Delete subtask |
GET | /api/orgs/{id}/issues/{issueId}/dependencies | List dependencies |
POST | /api/orgs/{id}/issues/{issueId}/dependencies | Add dependency |
DELETE | /api/orgs/{id}/issues/{issueId}/dependencies/{dependencyId} | Remove dependency |
GET | /api/orgs/{id}/labels | List org labels |
POST | /api/orgs/{id}/labels | Create label |
POST | /api/orgs/{id}/issues/{issueId}/labels | Add label to issue |
DELETE | /api/orgs/{id}/issues/{issueId}/labels/{labelId} | Remove label from issue |
GET | /api/orgs/{id}/issues/{issueId}/attachments | List private attachments with signed URLs |
POST | /api/orgs/{id}/issues/{issueId}/attachments | Upload private attachment |
GET | /api/orgs/{id}/issues/{issueId}/attachments/{attachmentId} | Redirect authorized requests to a fresh signed URL |
DELETE | /api/orgs/{id}/issues/{issueId}/attachments/{attachmentId} | Delete private attachment |
400 with body is required for direct comments or comment_body is required for issue updates with comment_body.
Structured mentions are recommended for agents and integrations. Direct comments accept mentions: [{ "member_id": "member-id" }]; issue update comments accept comment_mentions: [{ "member_id": "member-id" }]. Use the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML atoll:member links remain backward-compatible.
Responses that create comments include mentions: { requested, created, skipped }. Each skipped[] entry includes member_id and reason. Reasons are invalid_member_id, not_found, self_mention, no_project_access, guest_unprojected_issue, unsupported_member_type, and mentions_muted.
Issue attachments are stored privately. List and upload responses include short-lived signed URLs in url and url_expires_in: 3600. The individual attachment GET endpoint is a stable authenticated URL for embedded comment images and redirects to a fresh signed URL. Listing and individual GET require access to the issue’s project; upload and delete require write access.
Milestones
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/projects/{projectId}/milestones | List project milestones |
POST | /api/orgs/{id}/projects/{projectId}/milestones | Create milestone |
GET | /api/orgs/{id}/milestones/{milestoneId} | Get milestone |
PATCH | /api/orgs/{id}/milestones/{milestoneId} | Update milestone |
DELETE | /api/orgs/{id}/milestones/{milestoneId} | Delete milestone |
Goals, KPIs, and initiatives
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/goals | List goals |
POST | /api/orgs/{id}/goals | Create goal |
GET | /api/orgs/{id}/goals/{goalId} | Get goal |
PATCH | /api/orgs/{id}/goals/{goalId} | Update goal |
DELETE | /api/orgs/{id}/goals/{goalId} | Delete goal, owner/admin only |
GET | /api/orgs/{id}/kpis | List KPIs |
POST | /api/orgs/{id}/kpis | Create KPI |
GET | /api/orgs/{id}/kpis/{kpiId} | Get KPI |
PATCH | /api/orgs/{id}/kpis/{kpiId} | Update KPI |
DELETE | /api/orgs/{id}/kpis/{kpiId} | Delete KPI, owner/admin only |
GET | /api/orgs/{id}/kpis/{kpiId}/snapshots | List KPI snapshots |
POST | /api/orgs/{id}/kpis/{kpiId}/snapshots | Record KPI snapshot |
GET | /api/orgs/{id}/kpi-http-sync-policy | List exact-host KPI HTTP sync allowlist policy |
POST | /api/orgs/{id}/kpi-http-sync-policy | Add an allowed exact host, human admin only |
GET | /api/orgs/{id}/kpi-http-syncs | List org-wide KPI HTTP sync review rows for Settings; includes can_manage; admins get config/secret metadata, members get redacted status rows |
GET | /api/orgs/{id}/kpis/{kpiId}/http-syncs | List KPI HTTP syncs |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs | Create a draft KPI HTTP sync |
PUT | /api/orgs/{id}/kpis/{kpiId}/http-syncs | Validate a proposed KPI HTTP sync config without storing or running it |
GET | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId} | Get a KPI HTTP sync |
PATCH | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId} | Update a KPI HTTP sync draft, human admin only |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/validate | Validate a stored sync, human admin only |
GET | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets | List sanitized secret metadata, human admin only |
PUT | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets | Add or replace a sync secret value, human admin only |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/dry-run | Execute a sanitized dry run without writing a snapshot, human admin only |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/publish | Publish a validated, dry-run sync, human admin only |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/disable | Disable a sync, human admin only |
POST | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/run-now | Preview by default; write a snapshot only with explicit admin confirmation |
GET | /api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/runs | List sanitized sync run history (human admin only) |
GET | /api/orgs/{id}/initiatives | List initiatives; optional project_id, required for guest/project-scoped callers |
POST | /api/orgs/{id}/initiatives | Create initiative; optional project_id/projectId, required and editable for guest/project-scoped callers |
GET | /api/orgs/{id}/initiatives/{initiativeId} | Get initiative |
PATCH | /api/orgs/{id}/initiatives/{initiativeId} | Update initiative |
DELETE | /api/orgs/{id}/initiatives/{initiativeId} | Delete initiative, owner/admin only |
POST | /api/orgs/{id}/initiatives/{initiativeId}/projects | Add project to initiative |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/projects | Remove project from initiative |
GET | /api/orgs/{id}/initiatives/{initiativeId}/kpi-impacts | List KPI impact links |
POST | /api/orgs/{id}/initiatives/{initiativeId}/kpi-impacts | Add KPI impact link |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/kpi-impacts/{impactId} | Remove KPI impact link |
GET | /api/orgs/{id}/initiatives/{initiativeId}/issues | List linked issue links; add ?details=1 for accessible task details from linked projects, direct issue links, and linked milestones |
POST | /api/orgs/{id}/initiatives/{initiativeId}/issues | Link issue |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/issues/{issueId} | Unlink issue |
GET | /api/orgs/{id}/initiatives/{initiativeId}/milestones | List linked milestones |
POST | /api/orgs/{id}/initiatives/{initiativeId}/milestones | Link milestone |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/milestones/{milestoneId} | Unlink milestone |
GET | /api/orgs/{id}/initiatives/{initiativeId}/targets | List initiative targets |
POST | /api/orgs/{id}/initiatives/{initiativeId}/targets | Create target |
GET | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId} | Get target |
PATCH | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId} | Update target |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId} | Delete target |
GET | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/issues | List target issue links |
POST | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/issues | Link issue to target |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/issues/{issueId} | Unlink issue from target |
GET | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/milestones | List target milestone links |
POST | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/milestones | Link milestone to target |
DELETE | /api/orgs/{id}/initiatives/{initiativeId}/targets/{targetId}/milestones/{milestoneId} | Unlink milestone from target |
GET | /api/orgs/{id}/heartbeat | Agent heartbeat context |
GET | /api/orgs/{id}/strategy/audit | Audit strategy chain for structural gaps + health issues (guests forbidden) |
Members, teams, agents, and integrations
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/orgs/{id}/members | List members. Supports `type=human | agent; owner/admin callers can add includeEmail=1` to hydrate joined human account emails for settings/admin views. |
POST | /api/orgs/{id}/members | Invite human member | |
POST | /api/orgs/{id}/invitations/{invitationId}/resend | Resend a pending invitation; cooldown returns 429 with Retry-After | |
PATCH | /api/orgs/{id}/members/{memberId} | Update member | |
DELETE | /api/orgs/{id}/members/{memberId} | Remove member | |
GET | /api/orgs/{id}/member-onboarding | Read current human member onboarding | |
PATCH | /api/orgs/{id}/member-onboarding | Update current human member onboarding | |
GET | /api/orgs/{id}/profile | Get current member record | |
POST | /api/orgs/{id}/members/{memberId}/avatar | Upload avatar to the public avatars bucket | |
DELETE | /api/orgs/{id}/members/{memberId}/avatar | Remove avatar | |
GET | /api/orgs/{id}/teams | List teams | |
POST | /api/orgs/{id}/teams | Create team | |
PATCH | /api/orgs/{id}/teams/{teamId} | Update team | |
DELETE | /api/orgs/{id}/teams/{teamId} | Delete team | |
GET | /api/orgs/{id}/teams/{teamId}/members | List team members | |
POST | /api/orgs/{id}/teams/{teamId}/members | Add member to team | |
DELETE | /api/orgs/{id}/teams/{teamId}/members/{memberId} | Remove member from team | |
GET | /api/orgs/{id}/agents | List agents, owner/admin | |
GET | /api/orgs/{id}/agents/manageable | List agents the current human can manage | |
POST | /api/orgs/{id}/agents | Create org, project-scoped, or personal agent | |
DELETE | /api/orgs/{id}/agents/{agentId} | Revoke manageable agent | |
PATCH | /api/orgs/{id}/agents/{agentId}/projects | Replace project access for a manageable non-personal agent | |
POST | /api/orgs/{id}/projects/{projectId}/agents | Grant selected manageable agents access to a project | |
GET | /api/orgs/{id}/agents/{agentId}/keys | List manageable agent keys | |
POST | /api/orgs/{id}/agents/{agentId}/keys | Generate manageable agent key | |
DELETE | /api/orgs/{id}/agents/{agentId}/keys/{keyId} | Revoke manageable agent key | |
POST | /api/orgs/{id}/agents/{agentId}/rotate | Rotate all manageable agent keys | |
POST | /api/orgs/{id}/agents/{agentId}/install-snippets | Generate manageable agent install snippets | |
GET | /api/orgs/{id}/integrations | List integrations, owner/admin | |
POST | /api/orgs/{id}/integrations | Create integration | |
DELETE | /api/orgs/{id}/integrations/{integrationId} | Revoke integration | |
GET | /api/orgs/{id}/integrations/{integrationId}/keys | List integration keys | |
POST | /api/orgs/{id}/integrations/{integrationId}/keys | Generate integration key | |
DELETE | /api/orgs/{id}/integrations/{integrationId}/keys/{keyId} | Revoke integration key |
attachments bucket are served through an authenticated compatibility proxy after issue attachments become private.
Agent creation scopes: send { name, projectIds: [...] } for a project-scoped guest agent, or legacy { name, projectId, projectIds? } to include a default project. Send { name, personal: true } for a personal guest agent that inherits the human owner’s project access; personal creation rejects explicit projectId or projectIds. Omitting project scope creates an org-wide agent and remains owner/admin-only.
Boards, views, templates, updates, and analytics
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/projects/{projectId}/board-columns | List board columns, including optional agent guidance descriptions |
POST | /api/orgs/{id}/projects/{projectId}/board-columns | Create board column (description?) |
PATCH | /api/orgs/{id}/projects/{projectId}/board-columns/{columnId} | Update board column (description?, use null to clear) |
DELETE | /api/orgs/{id}/projects/{projectId}/board-columns/{columnId} | Delete board column |
PUT | /api/orgs/{id}/projects/{projectId}/board-columns/reorder | Reorder board columns |
GET | /api/orgs/{id}/projects/{projectId}/board-context | Get board milestone and initiative focus context |
GET | /api/orgs/{id}/projects/{projectId}/board-views | List board views |
POST | /api/orgs/{id}/projects/{projectId}/board-views | Create board view |
PATCH | /api/orgs/{id}/projects/{projectId}/board-views/{viewId} | Update board view |
DELETE | /api/orgs/{id}/projects/{projectId}/board-views/{viewId} | Delete board view |
GET | /api/orgs/{id}/projects/{projectId}/custom-views | List custom views |
POST | /api/orgs/{id}/projects/{projectId}/custom-views | Create custom view |
PATCH | /api/orgs/{id}/projects/{projectId}/custom-views/{viewId} | Update custom view |
DELETE | /api/orgs/{id}/projects/{projectId}/custom-views/{viewId} | Delete custom view |
GET | /api/orgs/{id}/templates?projectId=... | List issue templates |
POST | /api/orgs/{id}/templates | Create issue template |
PATCH | /api/orgs/{id}/templates/{templateId} | Update issue template |
DELETE | /api/orgs/{id}/templates/{templateId} | Delete issue template |
GET | /api/orgs/{id}/projects/{projectId}/status-updates | List project status updates |
POST | /api/orgs/{id}/projects/{projectId}/status-updates | Create project status update |
GET | /api/orgs/{id}/analytics?from=...&to=... | Get analytics |
GET | /api/orgs/{id}/activity | Organization activity feed |
Automation, webhooks, billing, and GitHub
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/automation-rules | List automation rules |
POST | /api/orgs/{id}/automation-rules | Create automation rule |
GET | /api/orgs/{id}/automation-rules/{ruleId} | Get automation rule |
PUT | /api/orgs/{id}/automation-rules/{ruleId} | Update automation rule |
DELETE | /api/orgs/{id}/automation-rules/{ruleId} | Delete automation rule |
GET | /api/orgs/{id}/automation-rules/{ruleId}/activity | Rule execution history |
POST | /api/orgs/{id}/automation-rules/{ruleId}/test | Dry-run test |
GET | /api/webhooks?orgId=... | List outbound webhooks |
POST | /api/webhooks?orgId=... | Create outbound webhook |
DELETE | /api/webhooks/{id} | Delete outbound webhook |
GET | /api/webhooks/{id}/deliveries | List webhook deliveries |
POST | /api/webhooks/{id}/redeliver/{deliveryId} | Redeliver webhook delivery |
POST | /api/webhooks/{id}/test | Send webhook test event |
GET | /api/orgs/{id}/billing | Get billing state; owner/admin read requests sync Stripe first and return 502 if that sync fails |
POST | /api/orgs/{id}/billing/checkout | Start a self-serve Stripe billing flow |
POST | /api/orgs/{id}/billing/portal | Create Stripe Billing Portal Session |
GET | /api/orgs/{id}/github-connections | List GitHub connections |
GET | /api/integrations/github/repos | List available repos |
POST | /api/integrations/github/connect | Connect repo |
POST | /api/integrations/github/disconnect | Disconnect repo |
Notifications and public endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/orgs/{id}/notifications | List unread actionable notifications for the current org member |
POST | /api/orgs/{id}/notifications/{notificationId}/ack | Acknowledge a current-member notification |
GET | /api/orgs/{id}/notifications/preferences | Read current-member notification preferences, including default-on mention notifications |
POST | /api/orgs/{id}/notifications/preferences | Update current-member notification preferences, including mention opt-out and cleanup |
GET | /api/notifications | List notifications |
POST | /api/notifications/{id}/read | Mark notification as read |
POST | /api/notifications/read-all | Mark all notifications as read |
GET | /api/health | Health check |
POST | /api/feedback | Public platform feedback endpoint, no auth |
mention.created, issue.assigned, comment.added, and issue.status_changed. Comment writes can request structured mentions with mentions[].member_id or comment_mentions[].member_id; comment-create responses include mention fanout proof. Notification preferences currently support mention opt-out for mention.created. Disabling in-app mention.created delivery also attempts to acknowledge that member’s currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat attention_items.