> ## 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 promotion > Creates a new promotion and its first version. For file-based formats (pdf, image, video, etc.), upload files first via the File API and provide uploadIds. For text format, provide inline content instead of uploadIds. Returns 409 if any referenced upload has not finished uploading to storage. ## OpenAPI ````yaml /openapi/integration-api.json post /v1/promotions 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: post: tags: - Promotions summary: Create promotion description: >- Creates a new promotion and its first version. For file-based formats (pdf, image, video, etc.), upload files first via the File API and provide uploadIds. For text format, provide inline content instead of uploadIds. Returns 409 if any referenced upload has not finished uploading to storage. operationId: createPromotion 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/CreatePromotionRequest' responses: '201': description: Promotion created content: application/json: schema: $ref: '#/components/schemas/CreatePromotionResponse' '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' '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: CreatePromotionRequest: 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) promotionName: type: string minLength: 1 description: Display name for the promotion channelIds: type: array items: type: string format: uuid minItems: 1 description: Channel IDs (from /v1/channels) productIds: type: array items: type: string format: uuid minItems: 1 description: Product IDs (from /v1/products) jurisdictionId: type: string format: uuid description: Jurisdiction ID (from /v1/jurisdictions) deadline: type: string format: date-time description: Deadline in ISO 8601 format paidPromotion: type: boolean description: Whether this is a paid promotion isFinancialPromotion: type: boolean description: Whether this is a financial promotion evergreen: type: boolean description: Whether this promotion is evergreen (no expiry) nextReviewDate: type: - string - 'null' format: date-time description: Next review date 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 - promotionName - channelIds - productIds - jurisdictionId CreatePromotionResponse: 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 ````