> ## 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. # List Figma frames > Lists the pages and frames of a Figma file so a frame can be selected for import via POST /v1/links. The file must be shared with "anyone with the link". This endpoint is limited to 10 requests per minute per API key. ## OpenAPI ````yaml /openapi/integration-api.json post /v1/links/figma/frames 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/figma/frames: post: tags: - Links summary: List Figma frames description: >- Lists the pages and frames of a Figma file so a frame can be selected for import via POST /v1/links. The file must be shared with "anyone with the link". This endpoint is limited to 10 requests per minute per API key. operationId: listFigmaFrames 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/FigmaFramesRequest' responses: '200': description: Pages and frames of the Figma file content: application/json: schema: $ref: '#/components/schemas/FigmaFramesResponse' '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: Figma file not found or not publicly accessible 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: FigmaFramesRequest: type: object properties: url: type: string maxLength: 2048 format: uri description: Figma file URL (figma.com) example: https://www.figma.com/design/AbCdEf123/My-Designs required: - url FigmaFramesResponse: type: object properties: fileName: type: string pages: type: array items: type: object properties: id: type: string name: type: string frames: type: array items: type: object properties: frameId: type: string description: Frame (node) ID — pass as figmaFrameId to POST /v1/links name: type: string width: type: number height: type: number required: - frameId - name required: - id - name - frames correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - fileName - pages - 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 ````