Skip to main content
Request bodies accept camelCase for common fields. Resource responses generally use snake_case; auth context uses the camelCase field names shown below.

Auth context

GET /api/auth/me returns one of two auth shapes. Human sessions include type: "human", userId, and orgId. Agent keys additionally include agentId, memberType, scopes, the live organization role, and projectAccess. OAuth-bound agent responses also include the non-secret oauth provenance object:
auth.oauth is present only for OAuth 2.1 access tokens. It identifies the consenting human, OAuth client, and exact protected resource; it never contains an access token, refresh token, or API key. API-key agent responses omit this object.

OAuth agent profiles

GET /api/oauth/agent-profiles returns the exact MCP resource and only the connection’s currently usable grants:
The profile reference is server-minted, opaque, and connection-scoped. It is not a credential and must not replace the bearer token or become shared mutable active-profile state. Project-scoped agents remain organization guests. projectAccess is the effective per-project authorization and is resolved from current membership data on every request. Key rotation is not required after role or project membership changes.

Avatar upload response

Successful POST /api/orgs/{id}/members/{memberId}/avatar requests return 200 with only the target member identifier and avatar URL:
No other member, invitation, onboarding, or account metadata is included. If the member pointer is updated but removal of the retired Storage object is still pending, the endpoint returns 202 with the same member projection plus "cleanup_pending": true. The DELETE endpoint likewise returns { "success": true, "cleanup_pending": true } with 202 when durable cleanup is queued. A concurrent pointer change returns { "error": "Avatar changed concurrently" } with 409; it includes the optional "cleanup_pending": true only if cleanup of a staged or retired object remains queued. A service-only scheduled worker drains due cleanup jobs every 15 minutes, with avatar requests providing an additional opportunistic sweep. Uploads over 2MB return 413.

Task fields

Most fields work on create and update unless a route says otherwise. labelIds is accepted on task create and bulk create. For existing tasks, use the label endpoints or atoll label add/remove. startDate and dueDate are date-only values in YYYY-MM-DD format. Recurring tasks use dueDate to compute the next generated task when the current task moves to done. Weekly tasks may set recurrenceDays to a unique array of weekday values from mon through sun. Responses normalize this as recurrence_days and expose { type, interval, days } in recurrence_schedule. Task detail responses include enriched member objects for creator, assignee, and assignees; each creator/assignee object includes id, display_name, type, and avatar_url when available. Full GET /api/orgs/{id}/issues list items include identifier, the canonical project-prefixed issue reference, and projectSlug, the collision-free project route segment. Both are null for projectless issues. Compact view=board and view=list items do not include these fields.

Task Activity fields

GET /api/orgs/{id}/activity returns { data, currentMemberId, limit, offset, hasMore }; it accepts limit, offset, and filter=all|by_me|mine. GET /api/orgs/{id}/issues/{issueId}/activity returns { data, items, limit, offset, hasMore }. Each event retains the activity_events fields. Top-level actor is a current member projection and can reflect later profile changes; the immutable event-time actor snapshot is metadata.actor with id, display_name, type, and avatar_url. The canonical action values are: issue.created, issue.updated, issue.archived, issue.unarchived, comment.created, comment.updated, comment.deleted, assignee.added, assignee.removed, label.added, label.removed, dependency.added, dependency.removed, dependency.release_updated, initiative.linked, initiative.unlinked, initiative_target.linked, initiative_target.unlinked, github_pr.linked, github_pr.updated, attachment.added, attachment.removed, subtask.created, subtask.completed, subtask.reopened, subtask.removed, and subtask.updated. metadata contains safe event snapshots and before/after changes. Notification, webhook, realtime, and delivery records are excluded. Pre-contract history may be partial because older events are not fabricated or backfilled.

Dependency fields

Dependency creation requires the blocking issue to belong to a project because the persistent release point is a board column in that project. A projectless issue may be the blocked target when the caller has permission to use it. GET /api/orgs/{id}/issues/{issueId}/dependencies returns blocking and blockedBy arrays. Each entry includes: Release-column fields are returned when the blocking issue is authorized. In the blocking list, the dependent target projection may be issue: null independently when that target is inaccessible. The dependency-release migration backfills existing dependencies to the blocking project’s done column before enforcing the persistent reference. During a rolling deployment, compatibility reads may omit release fields from older rows; treat missing release metadata as the legacy open-blocker behavior until the migration is applied.

Goal fields

KPI fields

Calculated task-completion KPIs use source_type: "formula" and are calculated from linked work instead of snapshots:
For goal_linked_issue_completion, current_value is the count of non-archived directly linked issues and milestone-linked issues in done status and target_value is the total non-archived directly linked issue and milestone-linked issue count under initiatives for the goal.

KPI snapshot fields

Recording a snapshot updates the KPI’s current_value. KPI-to-initiative impact links are separate from snapshot attribution. A link means the initiative is expected to move the KPI; snapshot attribution identifies the initiative and/or issue that produced one measurement. Calculated KPIs do not accept manual snapshots. api_poll snapshots are written by published KPI HTTP Syncs and include first-class provenance: source_sync_id, source_sync_run_id, source_config_hash, source_recorded_for, observed_at, and optional provider_recorded_at.

KPI detail relationship fields

GET /api/orgs/{id}/kpis/{kpiId} adds initiative_impacts to the kpi object. Each row represents an intended-impact relationship and includes the relationship identifiers, expected_impact, and a visible initiative object with its id, title, name, and status. The rows cover all initiative statuses and are filtered through project-aware initiative visibility. This is not KPI snapshot attribution.

KPI HTTP sync fields

KPI HTTP Syncs are constrained generic pollers: GET only, https only, JSON only, exact-host allowlisted, no redirects, no request bodies, no query strings, and no secret values in configs. Draft creation and config validation require the destination host to already be exactly allowlisted. Credential placeholders are limited to Authorization: Bearer <secretRef> and X-API-Key: <secretRef>. Human admins manage exact-host allowlists, secrets, dry-runs, publish, disable, and snapshot-writing run-now actions in Settings > Integrations > KPI syncs. Machine actors can create draft syncs and validate proposed configs only after the host is allowlisted. The org-wide Settings endpoint returns config and secret metadata only to human owners/admins; non-admin members receive redacted status rows, and guests/machine actors are denied.

KPI HTTP sync run fields

Run history is sanitized. It does not expose request headers, secret values, response bodies, or raw third-party payloads.

Board column mutation fields

Create a column with key, label, optional description, and optional color; it appends to the board. Patch accepts label, description, and color. Create and patch reject position—use the reorder endpoint instead. Delete a column with DELETE .../board-columns/{columnId}?reassignTo={targetColumnId}&releaseReassignTo={releaseTargetColumnId}. reassignTo is required when the source column contains issues and must name a column in the same project. releaseReassignTo is a separate target and is required when the source has dependency release references. The board-column list reports issue_count and release_reference_count so clients can fail closed before deletion. Reassignment and deletion are atomic, and the final board column cannot be deleted. Reorder with { "columns": [{ "id": "column-uuid", "position": 0 }] } and include every current column exactly once with unique non-negative positions.

Initiative fields

Create requests accept either title or legacy name; Atoll stores both fields from the trimmed value. Create requests also accept goalId, ownerId, targetDate, and projectId aliases for goal_id, owner_id, target_date, and project_id. Guest/project-scoped callers must use project_id and have edit/admin access to that project. GET /api/orgs/{id}/initiatives/{initiativeId} adds kpi_impacts to the initiative object. Only relationships whose linked KPIs are readable by the caller are embedded; unreadable KPI relationships are omitted. The rows are intended-impact links, not snapshot attribution records.
Initiative issue links and initiative-target issue links accept the following request shape:
issue_id may be an issue UUID, a bare number, #number, ATOLL-number, TSK-number, or an unambiguous project-derived prefix. Initiative milestone links use:
milestone_id may be a milestone UUID or its exact name. Resolution is scoped to the initiative’s authoritative projects and successful writes persist the canonical resource UUID. Target milestone links remain UUID-addressed.

Automation rule fields

Dry-run test body:
or:

Custom view fields

Webhook fields

The URL must be an HTTPS DNS hostname. IP literals, localhost, and .local hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a secret for HMAC verification. Store it immediately; it is shown only once. List responses include destination_display and a deprecated url compatibility field; both contain only the origin plus /…. Delivery requests include X-Atoll-Signature, X-Atoll-Signature-Version, versioned X-Atoll-Signatures, and X-Atoll-Delivery-Id. Payload schema version 2 is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery history includes delivery_id, status, status_code, error_code, delivered_at, and next_retry_at; it never includes payloads, receiver response bodies, or raw errors.

Private inbox fields

List responses omit message bodies, headers, action history, and drafts. Use the single-message endpoint only after selecting a queue item.

Strategy audit fields

GET /api/orgs/{id}/strategy/audit returns findings (sorted critical → warning → info), a summary, and counts_by_type. Each finding: Finding type values: initiative_orphaned, kpi_orphaned, goal_missing_kpi, goal_missing_initiative, dangling_initiative_project, dangling_initiative_issue, dangling_initiative_milestone (structural); kpi_unrecorded, kpi_missing_target, kpi_stale, kpi_off_pace (KPI health); initiative_missing_impact, initiative_missing_execution, initiative_stalled, initiative_target_missing_execution, initiative_target_overdue, initiative_target_blocked (initiative health); issue_blocked, issue_overdue, milestone_overdue (execution). Strategy audit findings are active-context findings. Paused and cancelled goals are excluded from active goal checks, KPIs attached to inactive goals are skipped for KPI health checks, and paused, completed, or cancelled initiatives are skipped for initiative health checks.

Enums

See Heartbeat API for the full recommended_action shape, suggested write fields, and response examples. Initiative targets use fields title, description, mode, unit, unit_label, current_value, target_value, target_direction, target_date, and due_soon_days. Use mode: "progress" for initiative output tracking and mode: "gate" for hard prerequisites. Gate target heartbeat messages use stateful language like 0/5 retailers complete; they do not emit KPI pace.