Skip to Content
annotyDocs
annotyDocs
annoty.appDashboardGetting started

Share with reviewers

Proxy or embed?ProxyEmbedScreenshotsToolbar position

Coding agents

Coding agents (MCP)Send to agent

Integrations

SlackWebhooksDiscordEmailZapiern8n

Reference

GlossaryPlans and billingGet help and send feedback
REST API
List a project's feedback sessions GETCreate a feedback session POSTList the organization's feedback sessions GETGet a feedback session GETUpdate a feedback session PATCHDelete a feedback session DELETEList where a feedback session was opened GET
REST APIFeedback sessions

Create a feedback session

List a project's feedback sessions GET

Newest first. Requires `feedbackSession:read`.

List the organization's feedback sessions GET

Every project's feedback sessions, newest first, each with its project's name. Requires `feedbackSession:read`.

POST
/v1/projects/{projectId}/feedback-sessions

Reviewers open it with its embedUrl, and with a proxy link too when you send proxy: true. Fails with 409 when the slug is taken. Requires feedbackSession:create and a plan with room for one more active feedback session, and with feedbackSessionPassword for a password.

Authorization

apiKey
headerAuthorizationBearer <token>

An organization API key from the dashboard (Settings → API keys), e.g. Authorization: Bearer annoty_.... x-api-key: annoty_... also works. While the organization has no subscription or trial, every request with a key except GET /v1/organization fails with 402 SUBSCRIPTION_REQUIRED.

Path Parameters

projectId*string

Request Body

application/json
  1. body
  1. body
  2. …
label*string
Length1 <= length <= 100
targetUrl*string

The site reviewers see, with the comment widget added

Formaturi
Lengthlength <= 2048
proxy?boolean

true gives the feedback session a proxy link on annoty.site. Left out, reviewers open it with its embed link only; a proxy link can be added later.

Defaultfalse
slug?string

The proxy link's subdomain on annoty.site, with proxy: true: 3 to 63 lowercase letters, digits and hyphens, unique across Annoty. Can't be changed once set. Defaults to the label plus 8 random characters; a custom slug is easier to guess.

Length3 <= length <= 63
expiresAt?|

The proxy link and the embed link stop working after this. Null for never.

Formatdate-time
password?string

What the proxy link asks for: 6 to 100 characters, trimmed. Needs a proxy link and a plan with feedbackSessionPassword.

Length6 <= length <= 100

Response Body

The created feedback session

application/json
  1. response
  1. response
  2. …
id*string
projectId*string
label*string
dataSession*|

Set when the project embed link created this feedback session: the embed script's data-session, or the page's host without one, slugified. The project embed link opens this feedback session again wherever the embed script names it.

slug*|

The proxy link's subdomain on annoty.site; null without a proxy link

proxyUrl*|

The proxy link: the target site on annoty.site with the comment toolbar on top. Nothing to install on the site. Anyone who has it can read and post comments. Null when the feedback session has none (proxy: false): reviewers open it with embedUrl only.

password*|

The proxy link asks for it before it shows the site, once per browser; null when it doesn't, or when there's no proxy link. Members who open the feedback session from the dashboard skip it. The embed link never asks for it. An empty string when it can't be read back: set a new one.

targetUrl*string
embedKey*string

The embed link's key. Put it in the embed script's data-key to open the toolbar on the target site without a link, for everyone who loads the page: that makes it public on the page. Anyone who has it can read and post comments.

embedUrl*string

The embed link: the target URL with an embed key in its fragment, which opens the comment toolbar on the site itself. Works once the site loads the embed script (embedScriptUrl), including behind a login. Like proxyUrl, anyone who has it can read and post comments.

embedScriptUrl*string

The embed script, which the target site loads on every page for embedUrl to work: <script async src="…"></script>. The same for every feedback session.

isActive*boolean
expiresAt*|
Formatdate-time
commentCount*integer

Comment threads; replies aren't counted

openCommentCount*integer
notificationsMuted*boolean

The project's notification destinations skip this feedback session; its own destinations still get its events

status*string

inactive when isActive is false, expired once expiresAt has passed. Only active feedback sessions open and count toward the plan's maxFeedbackSessions.

Value in"active""inactive""expired"
createdAt*string
Formatdate-time
Example Request
curl -X POST 'https://api.annoty.app/v1/projects/string/feedback-sessions' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "string",
  "targetUrl": "http://example.com"
}'
Example Response
{
  "id": "string",
  "projectId": "string",
  "label": "string",
  "dataSession": "string",
  "slug": "string",
  "proxyUrl": "string",
  "password": "string",
  "targetUrl": "string",
  "embedKey": "string",
  "embedUrl": "string",
  "embedScriptUrl": "string",
  "isActive": true,
  "expiresAt": "2019-08-24T14:15:22Z",
  "commentCount": 0,
  "openCommentCount": 0,
  "notificationsMuted": true,
  "status": "active",
  "createdAt": "2019-08-24T14:15:22Z"
}