> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myunite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a pre-test

> Creates a pre-test from a file you uploaded with POST /uploads. The response is 202: the analysis runs in the background. Poll GET /pretests/{id} until status is completed or failed. The Location header points to the new pre-test. The Idempotency-Key header is required: repeating a request with the same key and the same body returns the same pre-test with Idempotent-Replayed: true, and a different body returns 409. A workspace can have a limited number of API pre-tests in progress at once (about 10; the limit is approximate and can be exceeded briefly under concurrent requests): beyond it you get 429 concurrency_limit with Retry-After. An empty metadata object is the same as omitting it. Every 4xx rejection listed below happens before any quota is used. A 5xx response (or a dropped connection) can come after the pre-test was created: repeat the request with the same Idempotency-Key and the same body to get it back, and the pre-test is charged once. A new key creates another pre-test and can charge twice.

Requires the `pretests:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /pretests
openapi: 3.1.0
info:
  title: Unite API
  version: 1.0.0
  description: >-
    Run ad pre-tests from your own systems: upload a creative, create a
    pre-test, and read its result and PDF report. Every request needs an API key
    sent as a Bearer token. Every response carries an X-Request-Id header.
servers:
  - url: https://myunite.ai/api/v1
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: What you can send when you create a pre-test.
  - name: Uploads
    description: Send creative files.
  - name: Pretests
    description: Create pre-tests and read their results.
  - name: Quota
    description: How many pre-tests you can still run.
  - name: Webhooks
    description: Manage the endpoints that are notified when a pre-test changes.
paths:
  /pretests:
    post:
      tags:
        - Pretests
      summary: Create a pre-test
      description: >-
        Creates a pre-test from a file you uploaded with POST /uploads. The
        response is 202: the analysis runs in the background. Poll GET
        /pretests/{id} until status is completed or failed. The Location header
        points to the new pre-test. The Idempotency-Key header is required:
        repeating a request with the same key and the same body returns the same
        pre-test with Idempotent-Replayed: true, and a different body returns
        409. A workspace can have a limited number of API pre-tests in progress
        at once (about 10; the limit is approximate and can be exceeded briefly
        under concurrent requests): beyond it you get 429 concurrency_limit with
        Retry-After. An empty metadata object is the same as omitting it. Every
        4xx rejection listed below happens before any quota is used. A 5xx
        response (or a dropped connection) can come after the pre-test was
        created: repeat the request with the same Idempotency-Key and the same
        body to get it back, and the pre-test is charged once. A new key creates
        another pre-test and can charge twice.


        Requires the `pretests:write` scope.
      operationId: createPretest
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A unique value you generate for this request, 1 to 255 visible ASCII
            characters. A UUID works well. Keys are scoped to your workspace.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[\x21-\x7E]{1,255}$
        - name: Accept-Language
          in: header
          required: false
          description: >-
            Language of the result text when locale is not in the body. Defaults
            to pt.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePretestRequest'
      responses:
        '202':
          description: Pre-test accepted.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Location:
              $ref: '#/components/headers/Location'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pretest'
        '400':
          description: 'Error. Possible codes: invalid_request, idempotency_key_required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Error. Possible codes: invalid_api_key, api_key_revoked,
            api_key_expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Error. Possible codes: quota_exhausted.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Error. Possible codes: feature_not_enabled, key_owner_not_member,
            insufficient_scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Error. Possible codes: upload_not_found, brand_not_found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Error. Possible codes: idempotency_conflict,
            idempotency_key_retired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Error. Possible codes: invalid_request, invalid_ooh_format,
            invalid_placement, upload_invalid, file_too_large, video_too_long.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Error. Possible codes: rate_limited, concurrency_limit.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Error. Possible codes: internal_error.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreatePretestRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateOohPretestRequest'
        - $ref: '#/components/schemas/CreateDigitalPretestRequest'
        - $ref: '#/components/schemas/CreateEmailPretestRequest'
      discriminator:
        propertyName: channel
        mapping:
          ooh: '#/components/schemas/CreateOohPretestRequest'
          digital: '#/components/schemas/CreateDigitalPretestRequest'
          email: '#/components/schemas/CreateEmailPretestRequest'
    Pretest:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: pretest
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
          description: >-
            queued: accepted and waiting to start. processing: being analyzed.
            completed: result available. failed: see error.
        channel:
          type: string
          enum:
            - ooh
            - digital
            - email
        title:
          type: string
        locale:
          type: string
          description: Language of the result text (pt, en or es).
        createdAt:
          type: string
          description: ISO 8601 UTC.
        updatedAt:
          type: string
          description: ISO 8601 UTC.
        brand:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
            - type: 'null'
        creative:
          type: object
          properties:
            type:
              type: string
              enum:
                - image
                - video
            thumbnailUrl:
              type:
                - string
                - 'null'
          required:
            - type
            - thumbnailUrl
        result:
          anyOf:
            - type: object
              properties:
                score:
                  description: Overall score from 0 to 10.
                  type:
                    - number
                    - 'null'
                recommendation:
                  anyOf:
                    - type: string
                      enum:
                        - launch
                        - optimize
                        - iterate
                    - type: 'null'
                  description: >-
                    Null only when the stored recommendation is not one of the
                    three codes.
                recommendationLabel:
                  description: Display text of the recommendation in the result language.
                  type:
                    - string
                    - 'null'
                conclusion:
                  type:
                    - string
                    - 'null'
                pillars:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type:
                      - number
                      - 'null'
                  description: Score from 0 to 10 per pillar.
                findings:
                  type: array
                  items:
                    type: object
                    properties:
                      check:
                        type: string
                        description: Stable identifier of the check.
                      name:
                        type: string
                      category:
                        type: string
                      status:
                        type: string
                        enum:
                          - pass
                          - warn
                          - fail
                          - info
                          - pending
                      score:
                        type:
                          - number
                          - 'null'
                      summary:
                        type:
                          - string
                          - 'null'
                      optional:
                        type: boolean
                    required:
                      - check
                      - name
                      - category
                      - status
                      - score
                      - summary
                      - optional
                recommendations:
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                      description:
                        type: string
                      priority:
                        type: string
                        enum:
                          - high
                          - medium
                          - low
                      category:
                        type:
                          - string
                          - 'null'
                    required:
                      - title
                      - description
                      - priority
                      - category
                maps:
                  type: object
                  properties:
                    heatmap:
                      anyOf:
                        - type: object
                          properties:
                            url:
                              type: string
                              description: Link to the image or video.
                            mediaType:
                              type: string
                              enum:
                                - image/jpeg
                                - video/mp4
                          required:
                            - url
                            - mediaType
                        - type: 'null'
                    contrast:
                      anyOf:
                        - type: object
                          properties:
                            url:
                              type: string
                              description: Link to the image or video.
                            mediaType:
                              type: string
                              enum:
                                - image/jpeg
                                - video/mp4
                          required:
                            - url
                            - mediaType
                        - type: 'null'
                    focus:
                      anyOf:
                        - type: object
                          properties:
                            url:
                              type: string
                              description: Link to the image or video.
                            mediaType:
                              type: string
                              enum:
                                - image/jpeg
                                - video/mp4
                          required:
                            - url
                            - mediaType
                        - type: 'null'
                  required:
                    - heatmap
                    - contrast
                    - focus
              required:
                - score
                - recommendation
                - recommendationLabel
                - conclusion
                - pillars
                - findings
                - recommendations
                - maps
            - type: 'null'
          description: Present only when status is completed.
        report:
          type: object
          properties:
            status:
              type: string
              enum:
                - pending
                - generating
                - ready
                - failed
                - unavailable
              description: >-
                State of the PDF report. pending until it is generated: for OOH
                and digital it is usually generated automatically after the
                analysis completes, for email only when you request it with GET
                /pretests/{id}/report. unavailable when it finished without a
                download link.
            url:
              description: Download link, present when status is ready.
              type:
                - string
                - 'null'
          required:
            - status
            - url
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                  enum:
                    - video_too_long
                    - quota_exhausted
                    - dispatch_failed
                    - processing_failed
                message:
                  type: string
              required:
                - code
                - message
            - type: 'null'
          description: Present only when status is failed.
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
          description: The key-value pairs sent on creation. Empty when none were sent.
      required:
        - id
        - object
        - status
        - channel
        - title
        - locale
        - createdAt
        - updatedAt
        - brand
        - creative
        - result
        - report
        - error
        - metadata
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_api_key
                - api_key_revoked
                - api_key_expired
                - insufficient_scope
                - feature_not_enabled
                - key_owner_not_member
                - rate_limited
                - concurrency_limit
                - invalid_request
                - idempotency_key_required
                - idempotency_conflict
                - idempotency_key_retired
                - upload_not_found
                - upload_invalid
                - file_too_large
                - video_too_long
                - invalid_ooh_format
                - invalid_placement
                - brand_not_found
                - quota_exhausted
                - not_found
                - report_not_ready
                - webhook_url_rejected
                - webhook_endpoint_limit
                - internal_error
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message.
            message:
              type: string
              description: Human-readable explanation in English. Its wording can change.
            requestId:
              type: string
              description: >-
                Same value as the X-Request-Id response header. Quote it when
                you contact support.
            docUrl:
              type: string
              description: Page that explains this code.
            param:
              description: >-
                The field, query parameter or header the error refers to, when
                there is one.
              type: string
          required:
            - code
            - message
            - requestId
            - docUrl
      required:
        - error
    CreateOohPretestRequest:
      type: object
      properties:
        uploadId:
          type: string
          minLength: 1
          description: The uploadId returned by POST /uploads, after you sent the file.
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Name of the pre-test. A default is generated when omitted.
        brandId:
          type: string
          minLength: 1
          maxLength: 200
          description: A brand id from GET /catalog. Enables the brand checks.
        locale:
          type: string
          enum:
            - pt
            - en
            - es
          description: Language of the result text. Defaults to Accept-Language, then pt.
        metadata:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
          description: >-
            Up to 20 string key-value pairs that come back on the pre-test. Keys
            1 to 40 characters, values up to 500. An empty object is the same as
            omitting it.
          maxProperties: 20
        channel:
          type: string
          const: ooh
          description: Where the creative will run.
        ooh:
          type: object
          properties:
            format:
              type: string
              minLength: 1
              maxLength: 200
              description: An OOH format key from GET /catalog (ooh.formats[].key).
          required:
            - format
          additionalProperties: false
      required:
        - uploadId
        - channel
        - ooh
      additionalProperties: false
    CreateDigitalPretestRequest:
      type: object
      properties:
        uploadId:
          type: string
          minLength: 1
          description: The uploadId returned by POST /uploads, after you sent the file.
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Name of the pre-test. A default is generated when omitted.
        brandId:
          type: string
          minLength: 1
          maxLength: 200
          description: A brand id from GET /catalog. Enables the brand checks.
        locale:
          type: string
          enum:
            - pt
            - en
            - es
          description: Language of the result text. Defaults to Accept-Language, then pt.
        metadata:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
          description: >-
            Up to 20 string key-value pairs that come back on the pre-test. Keys
            1 to 40 characters, values up to 500. An empty object is the same as
            omitting it.
          maxProperties: 20
        channel:
          type: string
          const: digital
          description: Where the creative will run.
        digital:
          type: object
          properties:
            platform:
              type: string
              enum:
                - meta
                - tiktok
              description: Ad platform.
            placement:
              type: string
              enum:
                - feed
                - stories
                - reels
                - in_stream
              description: >-
                Placement. Values depend on the platform: see GET /catalog
                (digital.platforms[].placements). TikTok accepts feed only.
            objective:
              type: string
              enum:
                - awareness
                - traffic
                - sales
                - leads
              description: Campaign objective.
          required:
            - platform
            - placement
          additionalProperties: false
      required:
        - uploadId
        - channel
        - digital
      additionalProperties: false
    CreateEmailPretestRequest:
      type: object
      properties:
        uploadId:
          type: string
          minLength: 1
          description: The uploadId returned by POST /uploads, after you sent the file.
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Name of the pre-test. A default is generated when omitted.
        brandId:
          type: string
          minLength: 1
          maxLength: 200
          description: A brand id from GET /catalog. Enables the brand checks.
        locale:
          type: string
          enum:
            - pt
            - en
            - es
          description: Language of the result text. Defaults to Accept-Language, then pt.
        metadata:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
          description: >-
            Up to 20 string key-value pairs that come back on the pre-test. Keys
            1 to 40 characters, values up to 500. An empty object is the same as
            omitting it.
          maxProperties: 20
        channel:
          type: string
          const: email
          description: Where the creative will run.
        email:
          type: object
          properties:
            subject:
              type: string
              minLength: 1
              maxLength: 500
              description: Subject line of the email.
            preheader:
              type: string
              minLength: 1
              maxLength: 500
              description: Preheader text of the email.
            stage:
              type: string
              enum:
                - draft
                - final_review
              description: Review stage. Defaults to draft.
            type:
              type: string
              enum:
                - promotional
                - newsletter
                - transactional
                - lifecycle
                - welcome
              description: Kind of email.
          required:
            - subject
            - preheader
          additionalProperties: false
      required:
        - uploadId
        - channel
        - email
      additionalProperties: false
  headers:
    X-Request-Id:
      description: >-
        Identifier of this request. Quote it when you contact support. It is
        also in error.requestId.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        Requests allowed per minute for this key and bucket: 600 for reads, 60
        for writes. Sent on responses once the key is accepted. On 401 errors
        and on 403 errors raised while the key is checked they may be absent.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the oldest counted request leaves the window.
      schema:
        type: integer
    Location:
      description: Path of the created pre-test, for example /api/v1/pretests/{id}.
      schema:
        type: string
    Idempotent-Replayed:
      description: >-
        Sent as true when the response replays a pre-test created by an earlier
        request with the same Idempotency-Key.
      schema:
        type: string
        enum:
          - 'true'
    Retry-After:
      description: Seconds to wait before you try again.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key, sent as `Authorization: Bearer unite_live_...`. Create keys in
        the workspace settings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.