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:
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
SuccessfulPOST /api/orgs/{id}/members/{memberId}/avatar requests return
200 with only the target member identifier and avatar URL:
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
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
source_type: "formula" and are calculated from linked work instead of snapshots:
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
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
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
Board column mutation fields
Create a column withkey, 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
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 link fields
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
Custom view fields
Webhook fields
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.
