Comments

Comments are the feedback left on a promotion version, both Adclear AI findings and human review notes. Use the read endpoint to pull feedback into your own workflow, and the import endpoint to push external review comments back into Adclear.

Get comments

curl -s "$API_BASE/v1/promotions/$PROMOTION_ID/versions/$VERSION_ID/comments?limit=20&offset=0" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID"

const res = await fetch(
  `${API_BASE}/v1/promotions/${promotionId}/versions/${versionId}/comments?limit=20&offset=0`,
  { headers },
);
const { threads, pagination } = await res.json();

res = requests.get(
    f"{API_BASE}/v1/promotions/{promotion_id}/versions/{version_id}/comments",
    headers=headers,
    params={"limit": 20, "offset": 0},
)
threads = res.json()["threads"]

Response (200 OK):

{
  "threads": [
    {
      "id": "thread-uuid-...",
      "createdAt": "2026-08-10T12:00:00.000Z",
      "comment": {
        "id": "comment-uuid-...",
        "author": { "type": "ai", "userId": "adclear-ai", "name": "Adclear AI" },
        "content": "This claim needs a risk disclaimer.",
        "createdAt": "2026-08-10T12:00:00.000Z",
        "editedAt": null
      },
      "replies": [
        {
          "id": "comment-uuid-2",
          "author": { "type": "reviewer", "userId": "user-...", "name": "Jane Doe" },
          "content": "Agreed, disclaimer added in the next version.",
          "createdAt": "2026-08-10T12:05:00.000Z",
          "editedAt": null
        }
      ]
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "totalThreads": 1, "hasMore": false },
  "correlationId": "corr-uuid-..."
}

Each thread has one top-level comment and its replies in chronological order. Threads are ordered oldest first. The promotionId and versionId in the path must belong to your workspace, or the request returns 404.

Query parameters

Parameter	Default	Description
`limit`	`20`	Maximum threads to return, 1 to 100
`offset`	`0`	Number of threads to skip

Page through with offset. Keep requesting until pagination.hasMore is false.

Comment fields

Field	Description
`id`	Comment identifier
`author`	Who wrote it (see below)
`content`	The comment text
`createdAt`	When it was posted (ISO 8601)
`editedAt`	When it was last edited, or `null` if never edited

Author

Field	Description
`type`	`ai` for Adclear AI, `reviewer` for a human with review permission, `author` for the person who submitted the promotion
`userId`	Author identifier. Always `"adclear-ai"` for AI comments
`name`	Display name, or `null` if the user has not been synced yet. Fall back to `userId` when `null`

Pagination fields

Field	Description
`limit`	Maximum threads returned in this page
`offset`	Threads skipped before this page
`totalThreads`	Total threads on this version
`hasMore`	`true` when more threads exist after this page

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Import comments

Use this endpoint to push external review feedback (roots, replies, and action responses) onto the current latest version of a promotion. Each item is processed independently: one failure does not roll back the rest. Send externalCommentId on every item if you need safe sequential retries. If you omit it, a retry after an ambiguous failure may create duplicates. Two simultaneous duplicate requests can still race. Imported comments may not appear in Get comments immediately. Wait briefly before using GET to resolve parentCommentId.

curl -s -X POST "$API_BASE/v1/promotions/$PROMOTION_ID/versions/$VERSION_ID/comments" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-External-User-ID: $USER_ID" \
  -d '{
    "comments": [
      {
        "externalCommentId": "wf-100",
        "author": { "email": "reviewer@brand.com" },
        "content": "Please add the required disclaimer.",
        "uploadId": "00000000-0000-4000-8000-000000000099"
      }
    ]
  }'

const res = await fetch(
  `${API_BASE}/v1/promotions/${promotionId}/versions/${versionId}/comments`,
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      comments: [
        {
          externalCommentId: 'wf-100',
          author: { email: 'reviewer@brand.com' },
          content: 'Please add the required disclaimer.',
          uploadId: '00000000-0000-4000-8000-000000000099',
        },
      ],
    }),
  },
);
const { results, summary } = await res.json();

Response (200 OK, partial success):

{
  "results": [
    {
      "index": 0,
      "externalCommentId": "wf-100",
      "status": "created",
      "threadId": "th_...",
      "commentId": "cm_..."
    }
  ],
  "summary": { "created": 1, "skipped": 0, "rejected": 0 },
  "correlationId": "corr-uuid-..."
}

Author identity

Every human author must include author.email. The email must match an active Adclear user who belongs to your organization. Optional trace fields (displayName, sourceUserId, sourceRole) are accepted for logging but are not stored and never affect permissions. If the author cannot be resolved, the item is rejected with AUTHOR_UNAVAILABLE. The same message is used whether the email is unknown or the user is not a member, so the endpoint cannot be used to probe Adclear accounts.

Item types

Kind	Required fields	Notes
Root comment	`content`, `author.email`	On multi-upload versions, also send `uploadId`. Optional `location` anchors the thread.
Ordinary reply	`content`, one parent field	Use `parentCommentId` for an existing Adclear comment, or `parentExternalCommentId` for a root imported earlier (including later in the same batch). Replies must not send `uploadId` or `location`.
Action response	`action`, one parent field	Targets an Adclear AI thread. Canned actions may omit `content`; `action: "reply"` requires `content`.

Supported action values: agree_to_action, agree_will_action, dismiss, dispute, relevant_not_required, reply. To reply to an AI evaluation finding, use the commentId that each comment-backed issue carries in the evaluation-completed webhook as parentCommentId. Comment indexing is asynchronous, so a reply sent immediately after the webhook may be rejected with PARENT_NOT_FOUND; wait briefly and retry.

Location (roots only)

location must already be collapsed to a single point, timestamp, or exact text snippet. The server does not accept rectangles or time ranges, so collapse them before sending:

A region or bounding box → its centre point, as xRatio/yRatio.
A time range → its start, as timeSeconds.

Omit location entirely to create an unanchored thread, which appears in the comment sidebar rather than on the asset.

`location.type`	Fields	Upload format
`image`	`xRatio`, `yRatio` (0–1)	Image
`pdf`	`pageNumber` (1-based), `xRatio`, `yRatio`	PDF
`timecode`	`timeSeconds`	Video or audio
`text`	`textToFind`	Text

Per-item result codes

Code	Meaning
`AUTHOR_UNAVAILABLE`	Author email unknown, deleted, or not a member of this org
`PARENT_NOT_FOUND`	Parent id unresolved or belongs to another version
`UPLOAD_NOT_FOUND`	`uploadId` is not attached to this version
`LOCATION_INVALID`	Location shape or values invalid for the upload format
`ACTION_TARGET_INVALID`	Action response aimed at a non-AI thread
`DEDUP_CAPACITY_EXCEEDED`	Retry metadata capacity reached on the target thread
`INVALID_ITEM`	Shape violation for this item only
`WRITE_FAILED`	Persist failed for this item; other items may still succeed

Whole-request errors use the standard envelope: 404 when the promotion or version is not found, 409 when the version is not the latest, and 502 when author identity lookup is temporarily unavailable (no items are written).

Get started

Fundamentals

Adclear API

File API

Get comments

Query parameters

Comment fields

Author

Import comments

Author identity

Item types

Location (roots only)

Per-item result codes

​Get comments

​Query parameters

​Comment fields

​Author

​Pagination fields

​Import comments

​Author identity

​Item types

​Location (roots only)

​Per-item result codes

Get comments

Query parameters

Comment fields

Author

Pagination fields

Import comments

Author identity

Item types

Location (roots only)

Per-item result codes