# greatfeedback.ai

> Calibrated AI-twin reviews on docs, sites, PDFs, images, audio, video,
> plus an embeddable widget for real-user feedback. Designed to be used
> by humans AND by autonomous agents.

## Programmatic surface

- Base URL: https://api.greatfeedback.ai
- Auth: `Authorization: Bearer gfat_<token>` (mint at workspace settings, OWNER-only)
- OpenAPI: https://api.greatfeedback.ai/openapi.json
- API reference: https://greatfeedback.ai/docs/api
- Full agent guide: https://api.greatfeedback.ai/llms-full.txt

## Agent self-signup (PRIVATE BETA — currently closed)

`POST /api/v1/agents/register` returns 403 `{ "reason": "private_beta" }`
until self-signup opens. Until then the surface is human-gated:

1. Your operator requests access at https://greatfeedback.ai/signup.
2. We provision a workspace + `gfat_*` token by hand and reply by email.
3. Use the token exactly as the post-beta wire-shape will document.

Future shape (will return 200 once the gate opens):

```
POST https://api.greatfeedback.ai/api/v1/agents/register
{ "agent_name": "<your agent id>", "contact_email": "<owner email>" }
→ { workspace_id, token: "gfat_...", wallet_topup_url }
```

Pricing on the agent tier: $0.05 / review against a prepaid wallet.

## MCP

- Install: `claude mcp add greatfeedback https://api.greatfeedback.ai/mcp/<mcp_token>`
- Discovery: https://api.greatfeedback.ai/mcp.json
- Tools: list_annotations, read_annotation, acknowledge, reply, resolve,
  patch_annotation, run_personas, get_resolution_upload_url,
  attach_resolution, list_resolutions
- The `list_annotations` tool accepts an `auto_fix: bool` filter so an
  automation agent can pick only submissions the submitter authorised
  for unattended change. Use `attach_resolution` to record the fix
  (before/after screenshot keys, https diff URL, markdown explanation);
  the original submitter is notified automatically (email when an
  address is on file, otherwise a thread reply).

## Top entry points

- `GET /api/v1/sites` list workspace sites
- `GET /api/v1/sites/{id}/annotations?status=&since=&auto_fix=` list feedback
- `PATCH /api/v1/annotations/{id}` update status / summary / assignee
- `POST /api/v1/annotations/{id}/replies` post a reply
- `POST /api/v1/annotations/{id}/run-personas` trigger AI feedback
- `POST /api/v1/annotations/{id}/resolutions/upload-url` presign a
  before/after screenshot upload (`{ kind: "before"|"after",
  content_type: "image/png" }`)
- `POST /api/v1/annotations/{id}/resolutions` attach the fix
  (`{ before_key?, after_key?, diff_url?, explanation? }`; at least one)
- `GET /api/v1/annotations/{id}/resolutions` list the fixes attached

## Demo

Anonymous, captcha-gated, 1 call per IP per 24h:

```
POST https://api.greatfeedback.ai/api/demo/run
{ "url": "https://example.com", "persona_slug": "designer" }
```