> ## 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. # Submit a link > Captures a link as an image upload that can be used in promotions. Generic http(s) URLs are captured synchronously as a full-page screenshot — the call can take up to 2 minutes, so set a generous client timeout; returns 201 with an uploadId. Figma links (figma.com) are imported asynchronously via the Figma API — the file must be shared with "anyone with the link"; returns 202 with an uploadId to poll via GET /v1/links/{uploadId}. A frame must be identified via the node-id query parameter in the URL ("copy link to frame" in Figma) or the figmaFrameId field; discover frame IDs via POST /v1/links/figma/frames. This endpoint is limited to 10 requests per minute per API key. ## OpenAPI ````yaml /openapi/integration-api.json post /v1/links 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/links: post: tags: - Links summary: Submit a link description: >- Captures a link as an image upload that can be used in promotions. Generic http(s) URLs are captured synchronously as a full-page screenshot — the call can take up to 2 minutes, so set a generous client timeout; returns 201 with an uploadId. Figma links (figma.com) are imported asynchronously via the Figma API — the file must be shared with "anyone with the link"; returns 202 with an uploadId to poll via GET /v1/links/{uploadId}. A frame must be identified via the node-id query parameter in the URL ("copy link to frame" in Figma) or the figmaFrameId field; discover frame IDs via POST /v1/links/figma/frames. This endpoint is limited to 10 requests per minute per API key. operationId: captureLink parameters: - 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: required: true content: application/json: schema: $ref: '#/components/schemas/CaptureLinkRequest' responses: '201': description: URL captured — the upload is ready to use content: application/json: schema: $ref: '#/components/schemas/CaptureLinkResponse' '202': description: >- Figma import accepted — poll GET /v1/links/{uploadId} until status is "completed" content: application/json: schema: $ref: '#/components/schemas/CaptureLinkAcceptedResponse' '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' '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' '504': description: Capture timed out or the capture provider was unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: CaptureLinkRequest: type: object properties: url: type: string maxLength: 2048 format: uri description: >- The link to capture. Generic http(s) URLs are captured as a full-page screenshot. Figma links (figma.com) are imported as an image via the Figma API — the file must be shared with "anyone with the link", and a frame must be identified via a node-id in the URL ("copy link to frame" in Figma) or the figmaFrameId field. example: https://example.com/landing-page figmaFrameId: type: string minLength: 1 description: >- Figma frame (node) ID to import, e.g. "123:456". Only valid for figma.com URLs. When omitted, the node-id query parameter from the URL is used. Discover frame IDs via POST /v1/links/figma/frames. example: '123:456' required: - url CaptureLinkResponse: type: object properties: uploadId: type: string format: uuid description: >- Upload ID of the captured image. Pass in uploadIds when creating a promotion or version (with fileFormat "image"). status: type: string enum: - completed fileFormat: type: string enum: - image sourceUrl: type: string description: The submitted URL, echoed back originalFileName: type: string previewUrl: type: string description: Time-limited signed URL to preview the captured image correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - uploadId - status - fileFormat - sourceUrl - correlationId CaptureLinkAcceptedResponse: type: object properties: uploadId: type: string format: uuid description: >- Upload ID of the pending import. Poll GET /v1/links/{uploadId} until status is "completed", then use finalUploadId when creating a promotion or version. status: type: string enum: - processing fileFormat: type: string enum: - image sourceUrl: type: string description: The submitted URL, echoed back frameId: type: string description: Figma frame (node) ID being imported frameName: type: string statusUrl: type: string description: Relative URL to poll for import status example: /v1/links/6f1c1c2e-1234-4bcd-9e0f-abcdef012345 correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - uploadId - status - fileFormat - sourceUrl - frameId - statusUrl - 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 ````