> ## 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. # Create version > Creates a new version. Inherits promotionName, channel, product, and jurisdiction from the existing promotion. For file-based formats, provide uploadIds. For text format, provide inline content instead. Returns 409 if any referenced upload has not finished uploading to storage. ## OpenAPI ````yaml /openapi/integration-api.json post /v1/promotions/{promotionId}/versions 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) ``` ### 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: 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: post: tags: - Promotions summary: Create version description: >- Creates a new version. Inherits promotionName, channel, product, and jurisdiction from the existing promotion. For file-based formats, provide uploadIds. For text format, provide inline content instead. Returns 409 if any referenced upload has not finished uploading to storage. operationId: createVersion parameters: - schema: type: string format: uuid description: Promotion ID required: true name: promotionId 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: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVersionRequest' responses: '201': description: Version created content: application/json: schema: $ref: '#/components/schemas/CreateVersionResponse' '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 not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- One or more uploads are not ready — the file has not finished uploading to storage. Retry after a short delay. The `details` array contains `upload_not_ready` entries with the offending `uploadId`(s). 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: CreateVersionRequest: type: object properties: uploadIds: type: array items: type: string format: uuid description: >- Upload IDs from the File API. Required for file-based formats (pdf, image, video, etc.). Must be omitted when fileFormat is "text". content: type: string minLength: 1 description: >- Inline text or HTML content. Required when fileFormat is "text". Must be omitted for file-based formats. fileFormat: type: string enum: - text - video - audio - image - pdf - document description: Content format (text, video, audio, image, pdf, document) deadline: type: string format: date-time description: Deadline in ISO 8601 format caption: type: string details: type: string type: type: string enum: - single - batch - carousel - variations description: Promotion type (single, batch, carousel, variations) linkedClaimIds: type: array items: type: string format: uuid targetMarketIds: type: array items: type: string format: uuid applyToAllTargetMarkets: type: boolean metadata: type: object additionalProperties: type: string maxLength: 1024 description: >- Arbitrary key-value pairs stored with the promotion and echoed back in webhook payloads. Max 20 keys. Keys: alphanumeric/underscore/hyphen, max 128 chars. Values: max 1024 chars. Do not store PII, credentials, or sensitive data. example: workfrontProjectId: PROJ-123 workfrontTaskId: TASK-456 workfrontDocumentId: DOC-789 required: - fileFormat CreateVersionResponse: type: object properties: promotionId: type: string format: uuid versionId: type: string format: uuid version: type: integer exclusiveMinimum: 0 description: Auto-derived version number metadata: type: object additionalProperties: type: string description: Stored metadata echoed back for confirmation correlationId: type: string format: uuid description: Correlation ID for request tracing. Include in support requests. required: - promotionId - versionId - version - 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 ````