> ## Documentation Index > Fetch the complete documentation index at: https://docs.adclear.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get comments > Returns comments on a version — AI-generated and human review — grouped into paginated threads. Each thread has one top-level comment plus its replies in chronological order. ## OpenAPI ````yaml /openapi/integration-api.json get /v1/promotions/{promotionId}/versions/{versionId}/comments openapi: 3.1.0 info: title: Adclear Public API version: 1.0.0 description: > REST API for managing promotions, versions, evaluations, and reference data. ## Authentication All requests require a Bearer token (Unkey API key) and the `X-External-User-ID` header. `X-External-User-Email` is optional. ## Quick Start ### 1. Upload files Use the **File API** at `files.adclear.ai` ([docs](https://files.adclear.ai/v1/docs)): ``` POST https://files.adclear.ai/v1/uploads → { uploadId, uploadUrl } PUT {uploadUrl} (binary file) ``` ### 1b. Or submit a link Generic URLs are captured synchronously as a full-page screenshot (up to 2 minutes — set a generous client timeout). Limited to 10 requests per minute per API key. ``` POST /v1/links { url } → 201 { uploadId, fileFormat: "image" } ``` Figma links import asynchronously. The file must be shared with "anyone with the link", and a frame must be identified via the node-id in the URL ("copy link to frame" in Figma), the `figmaFrameId` field, or discovery via `POST /v1/links/figma/frames`: ``` POST /v1/links { url: "https://www.figma.com/design/KEY/Name?node-id=1-23" } → 202 { uploadId, statusUrl } GET /v1/links/{uploadId} (poll every few seconds) → 200 { status: "completed", finalUploadId } ``` Use the resulting uploadId (or `finalUploadId` for Figma) with `fileFormat: "image"` when creating a promotion. Very large Figma frames (over ~6 megapixels) cannot be imported via the API yet. ### 2. Create a promotion ``` POST /v1/promotions { uploadIds, fileFormat, promotionName, ... } → 201 { promotionId, versionId } → 409 if uploads not yet ready (retry after a short delay) ``` ### 3. Trigger evaluation ``` POST /v1/promotions/{id}/versions/{id}/evaluate → 202 { evaluationId, status: "processing" } ``` ### 4. Receive results via webhook An `evaluation-completed` webhook is sent to your configured endpoint with the evaluation status, issue count, and any metadata you provided. ### 5. Submit revisions (if needed) Upload new files, then create a new version on the same promotion: ``` POST /v1/promotions/{id}/versions { uploadIds, fileFormat, ... } → 201 { versionId, version: 2 } ``` --- servers: - url: https://public-api.adclear.ai description: Production - url: https://public-api-staging.adclear.ai description: Staging security: - BearerAuth: [] tags: - name: Promotions description: Promotion and version management - name: Links description: Submit URLs and public Figma links as image uploads for promotions - name: Evaluation description: AI evaluation triggers and results - name: Reference Data description: Read-only lookups for products, channels, jurisdictions, target markets externalDocs: description: File uploads are handled by the File Proxy API (files.adclear.ai) url: https://files.adclear.ai/v1/docs paths: /v1/promotions/{promotionId}/versions/{versionId}/comments: get: tags: - Evaluation summary: Get comments description: >- Returns comments on a version — AI-generated and human review — grouped into paginated threads. Each thread has one top-level comment plus its replies in chronological order. operationId: getComments parameters: - schema: type: string format: uuid description: Promotion ID required: true name: promotionId in: path - schema: type: string format: uuid description: Version ID required: true name: versionId in: path - schema: type: string description: Maximum number of threads to return (1–100, default 20) example: '20' required: false name: limit in: query - schema: type: string description: Number of threads to skip (default 0) example: '0' required: false name: offset in: query - name: X-External-User-ID in: header required: true schema: type: string description: External user identifier from the calling system - name: X-External-User-Email in: header required: false schema: type: string format: email description: External user email from the calling system responses: '200': description: Comment threads for the version content: application/json: schema: $ref: '#/components/schemas/GetCommentsResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Promotion or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: GetCommentsResponse: type: object properties: threads: type: array items: $ref: '#/components/schemas/CommentThread' description: >- Comment threads on this page, oldest thread first. Each thread includes its top-level comment and replies. pagination: $ref: '#/components/schemas/CommentThreadPagination' correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - threads - pagination - correlationId ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - VALIDATION_ERROR - INVALID_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - PAYLOAD_TOO_LARGE - RATE_LIMITED - INTERNAL_ERROR - UPSTREAM_ERROR message: type: string details: type: array items: oneOf: - type: object properties: type: type: string enum: - field_error field: type: string message: type: string required: - type - field - message - type: object properties: type: type: string enum: - constraint_violation constraint: type: string limit: type: number actual: type: number required: - type - constraint - limit - actual - type: object properties: type: type: string enum: - retry_info retryAfterSeconds: type: number required: - type - retryAfterSeconds - type: object properties: type: type: string enum: - upload_not_ready uploadId: type: string format: uuid required: - type - uploadId required: - code - message correlationId: type: string format: uuid required: - error - correlationId CommentThread: type: object properties: id: type: string description: Thread identifier createdAt: type: string format: date-time description: When the thread started (its earliest comment) comment: $ref: '#/components/schemas/Comment' replies: type: array items: $ref: '#/components/schemas/Comment' description: Replies in chronological order. Empty when there are none. required: - id - createdAt - comment - replies CommentThreadPagination: type: object properties: limit: type: integer description: Maximum number of threads returned in this page offset: type: integer description: Number of threads skipped before this page totalThreads: type: integer description: Total number of threads on this version hasMore: type: boolean description: True when more threads exist after this page required: - limit - offset - totalThreads - hasMore Comment: type: object properties: id: type: string author: $ref: '#/components/schemas/CommentAuthor' content: type: string createdAt: type: string format: date-time editedAt: type: - string - 'null' format: date-time description: When the comment was last edited, or null if never edited required: - id - author - content - createdAt - editedAt description: The top-level comment that started the thread CommentAuthor: type: object properties: type: type: string enum: - ai - reviewer - author description: >- Who wrote the comment. `ai` is Adclear AI; `reviewer` is a human with review permission; `author` is the person who submitted the promotion. userId: type: string description: Author identifier. Always the literal "adclear-ai" for AI comments. name: type: - string - 'null' description: >- Display name, or null when the author has not been synced yet. Fall back to userId when null. required: - type - userId - name securitySchemes: BearerAuth: type: http scheme: bearer description: Unkey API key passed as Bearer token ````