> ## 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. # Record decision > Records the authoritative human review decision on a version: approve, reject, or request changes. The decision is permission-gated on the reviewer's access to the promotion's country. ## OpenAPI ````yaml /openapi/integration-api.json post /v1/promotions/{promotionId}/versions/{versionId}/decision 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 {statusUrl} (poll every few seconds) → 200 { status: "completed", finalUploadId } ``` Google Drive and Google Docs links import asynchronously too, and must also be shared with "anyone with the link" (the API has no connected Google account, so private files are unreachable). Native Docs, Sheets and Slides are converted to PDF: ``` POST /v1/links { url: "https://docs.google.com/document/d/KEY/edit" } → 202 { uploadId, fileFormat: "pdf", source: "gdrive", statusUrl } GET {statusUrl} (poll every few seconds) → 200 { status: "completed", finalUploadId } ``` Always poll `statusUrl` exactly as returned — it carries the source the poll needs. Use the resulting uploadId (or `finalUploadId`) when creating a promotion, with the `fileFormat` from the capture response rather than a fixed value: screenshots and Figma frames are always `image`, but a Drive file can be any supported format. 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, public Figma frames and public Google Drive files as 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}/decision: post: tags: - Review summary: Record decision description: >- Records the authoritative human review decision on a version: approve, reject, or request changes. The decision is permission-gated on the reviewer's access to the promotion's country. operationId: recordDecision 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 - 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/DecisionRequest' responses: '200': description: Decision recorded content: application/json: schema: $ref: '#/components/schemas/DecisionResponse' '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' '403': description: Not permitted to review this promotion content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Promotion or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Version cannot be decided in its current state 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: DecisionRequest: type: object properties: decision: type: string enum: - approved - rejected - changes_requested description: >- The human review decision to record on the version. Uses the same vocabulary as GET .../decision and the review.* webhooks. example: approved required: - decision DecisionResponse: type: object properties: success: type: boolean correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - success - 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 securitySchemes: BearerAuth: type: http scheme: bearer description: Unkey API key passed as Bearer token ````