# greatfeedback.ai API reference

The /api/v1/* surface is the stable programmatic API. Use it from CI scripts, language SDKs, or any Claude Code agent that needs to read or update workspace annotations.

For dashboard-style flows, the same endpoints accept a Cognito session, so the FE composables and a third-party CLI share one contract.

# Base URLs

# Authentication

Pass the bearer token in the standard Authorization header.

# API token (recommended for programmatic callers)

Authorization: Bearer gfat_<token>

Tokens are minted in the dashboard at workspace settings → API tokens, or via POST /api/workspaces/{ws}/api-tokens (OWNER role required to mint). Tokens are clamped to MEMBER or GUEST at issuance — OWNER and ADMIN are not assignable. The plaintext is shown ONCE at creation time; only the SHA-256 hash + last-4 chars persist on the row.

# Cognito session

Authorization: Bearer <Cognito ID token>

The dashboard FE uses this. Same /api/v1/* endpoints work for both auth styles; route handlers don't care which one was used.

# Required headers

API tokens carry their workspace id internally — no X-GF-Workspace header is needed when using gfat_*.

# Endpoints

# Sites

# Annotations

GUEST tokens that try run-personas get 403 with Insufficient role.

The auto_fix=true|false filter restricts to (or excludes) submissions the original submitter authorised for unattended automated change. See § Auto-fix and resolution evidence.

# Resolutions (auto-fix evidence)

A RESOLUTION row records what changed to address the annotation. Multiple resolutions per annotation are allowed (fix → revert → re-fix). On create, the original submitter is notified asynchronously: by Resend email if their address is on file, otherwise via a REPLY row appended to the annotation thread (visible to anonymous submitters when they revisit the page). The notification_status field on the row reports the outcome.

# API tokens (workspace settings)

These management endpoints are session-only; you cannot mint or revoke a token via another token.

# Secrets (dashboard-only)

API tokens cannot read these endpoints. Tokens are clamped to MEMBER, while secrets require OWNER, so the auth check fails. The dashboard is the only place that ever reveals mcp_token or widget_token.

# Personas

Each new workspace is seeded with 60 default personas (is_default=true) at creation. is_built_in is no longer part of the API; the legacy GET /api/personas/built-in endpoint is removed.

# MCP tools

Configure once: claude mcp add greatfeedback https://api.greatfeedback.ai/mcp/<mcp_token>.

The MCP server exposes:

• list_annotations(status?, kind?, since?, auto_fix?, limit?) — discover open work. Pass auto_fix=true to pick only submissions the submitter authorised for unattended automated change.
• read_annotation(id) — full body, screenshot, computed styles, replies, markdown.
• acknowledge(id) — flip status * -> ack.
• reply(id, message) — post an agent reply on the thread.
• resolve(id, summary) — flip status * -> resolved with a summary.
• patch_annotation(id, status?, summary?, assignee_id?) — generalised write.
• get_resolution_upload_url(annotation_id, kind, content_type) — presign a before / after screenshot upload. Returns {url, method, headers, key, expires_in_seconds}. PUT bytes to url with headers, then pass key back to attach_resolution.
• attach_resolution(annotation_id, before_key?, after_key?, diff_url?, explanation?) — append a RESOLUTION row recording what changed. At least one of the four fields must be present; diff_url must be https://; explanation is markdown, 4 KB cap. Auto-notifies the submitter (email when an address is on file, otherwise a thread reply).
• list_resolutions(annotation_id) — list the resolutions already attached, oldest-first. Use this to avoid duplicating work.
• run_personas(id, persona_ids?) — kick off the AI persona pipeline.

# Auto-fix and resolution evidence

Each annotation carries an auto_fix boolean. When true, the submitter authorised the consumer system (an agent, a CI bot, the engineering team) to apply the change without further discussion. Anonymous submitters always land false regardless of what the client sent — the server coerces.

Stakeholder tokens have a per-row auto_fix_default (never | optional_off | optional_on) that gates whether the toggle renders for them in the widget at all and what initial state it has. Manage via:

End-to-end agent flow:

TOKEN=gfat_<your token>
ANN=$(curl -sH "Authorization: Bearer $TOKEN" \
  "https://api.greatfeedback.ai/api/v1/sites/<site>/annotations?auto_fix=true" \
  | jq -r '.items[0].id')

# Upload screenshots (optional)
PRE=$(curl -sX POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"kind":"after","content_type":"image/png"}' \
  "https://api.greatfeedback.ai/api/v1/annotations/$ANN/resolutions/upload-url")
URL=$(echo "$PRE" | jq -r .url); KEY=$(echo "$PRE" | jq -r .key)
curl -X PUT --data-binary @after.png -H "Content-Type: image/png" "$URL"

# Attach the resolution
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"after_key\":\"$KEY\",\"diff_url\":\"https://github.com/x/y/pull/42\",\"explanation\":\"Increased CTA contrast.\"}" \
  "https://api.greatfeedback.ai/api/v1/annotations/$ANN/resolutions"

MCP tokens authenticate the caller as the site's MCP integration; every write tool stamps the audit log with actor_id="mcp:<site_id>" so an operator can grep MCP calls separately from human or API-token actions.

# Status taxonomy

"new" | "ack" | "triaged" | "in_progress" | "resolved" | "won_t_fix" | "duplicate"

• new — created via the widget; nobody's looked at it yet.
• ack — "we saw it"; no work yet.
• triaged — looked at and filed (e.g., into Linear/Jira). Distinct from ack.
• in_progress — work underway.
• resolved — done.
• won_t_fix — closed without action.
• duplicate — closed because another annotation covers it; pair with a summary like "duplicate of ".

Unknown status values 400 at request validation.

# Pagination

List endpoints accept ?cursor=...&limit=.... Default limit 50, max 200.

Cursors are server-issued and HMAC-tamper-protected. A tampered cursor 400s; a missing cursor returns the first page. The cursor encodes the last row's sort key plus a signature; decoding it without the secret is rejected.

GET /api/v1/sites/{id}/annotations?limit=50
→ { "items": [...], "next_cursor": "<opaque>" }

GET /api/v1/sites/{id}/annotations?limit=50&cursor=<opaque>
→ { "items": [...], "next_cursor": "<opaque or null>" }

The last page returns "next_cursor": null.

# Rate limits

Both buckets must allow the request. Excess returns 429 with a reason string. Recovery happens automatically once the 60-second window rolls over.

The WAF adds an additional per-IP rule at the edge — those rejections never reach the application layer and don't appear in audit logs.

# HTTP error codes

401 responses include a WWW-Authenticate: Bearer error="invalid_token" challenge with the failure reason in error_description. Clients should treat any 401 as "stop retrying with this credential" and either rotate the token or sign in again.

A workspace soft-deleted in the 30-day grace window returns 401 to API-token callers (so a CI loop stops retrying) and 403 to session callers (so the FE can render the "restore" banner). The OWNER restoring the workspace flips both back to 200.

# Quick start (curl)

TOKEN=gfat_<your token>

# List sites
curl -H "Authorization: Bearer $TOKEN" \
  https://api.greatfeedback.ai/api/v1/sites

# List annotations on a site
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.greatfeedback.ai/api/v1/sites/$SITE_ID/annotations?status=new"

# Mark one resolved
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved","summary":"shipped in v2"}' \
  https://api.greatfeedback.ai/api/v1/annotations/$ANN_ID

# Reply on the thread
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"fixed in #1234"}' \
  https://api.greatfeedback.ai/api/v1/annotations/$ANN_ID/replies

# Token rotation

There's no rotation grace period — revoking a token invalidates it immediately. To rotate:

1. Mint a new token in the dashboard.
2. Roll the new token into your secret manager.
3. Confirm the new token works against /api/v1/sites.
4. Revoke the old token.

If you suspect a token leaked, revoke first and ask questions later.

# Claude Code skill

A higher-level skill that wraps these endpoints in slash commands ships from a separate repo: great-feedback-skill. The skill speaks MCP for read paths and curls /api/v1/* for writes; an install.sh writes both configs.