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 projects GETCreate a project POSTGet a project GETUpdate a project PATCHDelete a project DELETERegenerate the project embed link POST
REST APIProjects

Update a project

Get a project GET

Requires `project:read`.

Delete a project DELETE

Fails with 409 while the project still has feedback sessions. Requires `project:delete`.

PATCH
/v1/projects/{projectId}

Only the fields you send change. Requires project:update.

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. …
name?string
Length1 <= length <= 100
domain?|

The site's domain, e.g. example.com. Stored lowercase. Optional; null clears it.

Length1 <= length <= 253
allowedHosts?array<>

Up to 3 hosts or patterns, on any site: staging.example.com, or one * in the first label for preview deploys, like *.my-app.pages.dev, *--my-site.netlify.app or my-app-git-*-team.vercel.app. A * matches part of one label only. Stored lowercase; repeats are dropped.

Itemsitems <= 3
screenshotsEnabled?boolean

Whether new comments carry a screenshot of what the reviewer saw. Defaults to true.

toolbarPosition?string

The corner the review toolbar opens in. Defaults to bottom-right.

Value in"top-left""top-right""bottom-left""bottom-right"

Response Body

The updated project

application/json
  1. response
  1. response
  2. …
id*string
name*string
domain*string|null
faviconUrl*|

The site's icon, fetched from domain in the background once it's set or changed, and refreshed monthly. Null without a domain, until the icon is found (usually a few seconds after saving), or when the site has none we could fetch.

allowedHosts*array<string>

Where the project embed link works besides domain, like staging sites and preview deploys: hosts, or patterns with one * in the first label, matching one or more characters of that label.

embedKey*string

The project embed link's key. Add #annoty=<embedKey> to the address of any page on domain or allowedHosts to link reviewers to that page, or put it in the embed script's data-key to open the toolbar there without a link, for everyone who loads the page. Anyone who has it can read and post comments on every feedback session it opens, and create new ones. Regenerate it to end every project embed link shared so far, and every data-key with it.

embedUrl*|

The project embed link on domain, null without one. On a site that loads the embed script, it opens the feedback session the script's data-session names and creates it on first use; without data-session, the one for the page's host.

embedScriptUrl*string

The embed script: <script async src="…" data-session="…"></script> on every page of the site.

screenshotsEnabled*boolean

Whether new comments carry a screenshot of what the reviewer saw. Turn it off for a site with customer data on screen: widgets stop taking them, on proxy links and embed links alike, from their next comment. Screenshots taken before stay with their comments.

toolbarPosition*string

The corner the review toolbar opens in, on proxy links and embed links alike: top-left, top-right, bottom-left or bottom-right. A reviewer who moves the toolbar keeps their own corner, and the embed script's data-position overrides this on its site.

Value in"top-left""top-right""bottom-left""bottom-right"
createdAt*string
Formatdate-time
Example Request
curl -X PATCH 'https://api.annoty.app/v1/projects/string' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
{
  "id": "string",
  "name": "string",
  "domain": "string",
  "faviconUrl": "string",
  "allowedHosts": [
    "string"
  ],
  "embedKey": "string",
  "embedUrl": "string",
  "embedScriptUrl": "string",
  "screenshotsEnabled": true,
  "toolbarPosition": "top-left",
  "createdAt": "2019-08-24T14:15:22Z"
}