> ## 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 an upload target for a creative file

> Creates a pre-signed URL to upload a creative file. Send the file with a PUT to uploadUrl, using the method and every header returned in headers, with exactly those values (Cache-Control is part of them). The URL is valid for 15 minutes. Then pass uploadId when you create the pre-test. Accepted types: PNG, JPEG, WebP and GIF images, MP4 and QuickTime videos (images up to 25 MB, videos up to 200 MB). The file content is checked when you create the pre-test, not at upload time. A body that is not valid JSON is 400; a field that is missing, wrongly typed or unknown is 422 invalid_request; an unsupported contentType is 422 upload_invalid.

Requires the `pretests:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /uploads
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:
  /uploads:
    post:
      tags:
        - Uploads
      summary: Create an upload target for a creative file
      description: >-
        Creates a pre-signed URL to upload a creative file. Send the file with a
        PUT to uploadUrl, using the method and every header returned in headers,
        with exactly those values (Cache-Control is part of them). The URL is
        valid for 15 minutes. Then pass uploadId when you create the pre-test.
        Accepted types: PNG, JPEG, WebP and GIF images, MP4 and QuickTime videos
        (images up to 25 MB, videos up to 200 MB). The file content is checked
        when you create the pre-test, not at upload time. A body that is not
        valid JSON is 400; a field that is missing, wrongly typed or unknown is
        422 invalid_request; an unsupported contentType is 422 upload_invalid.


        Requires the `pretests:write` scope.
      operationId: createUpload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '201':
          description: Upload target.
          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/UploadTarget'
        '400':
          description: 'Error. Possible codes: invalid_request.'
          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'
        '403':
          description: >-
            Error. Possible codes: feature_not_enabled, key_owner_not_member,
            insufficient_scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Error. Possible codes: invalid_request, upload_invalid,
            file_too_large.
          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.'
          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:
    UploadRequest:
      type: object
      properties:
        contentType:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
            - image/gif
            - video/mp4
            - video/quicktime
          description: Content type of the file you will upload.
        sizeBytes:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          description: >-
            Declared size in bytes: images up to 25 MB, videos up to 200 MB. The
            stored object is measured again when you create the pre-test.
        filename:
          description: Original file name. Informational only.
          type: string
          maxLength: 255
      required:
        - contentType
        - sizeBytes
      additionalProperties: false
    UploadTarget:
      type: object
      properties:
        uploadId:
          type: string
          description: Pass this as uploadId when you create the pre-test.
        uploadUrl:
          type: string
          description: >-
            Pre-signed URL. Send the file to it with the method and headers
            below.
        method:
          type: string
          const: PUT
        headers:
          type: object
          properties:
            Content-Type:
              type: string
            Cache-Control:
              type: string
          required:
            - Content-Type
            - Cache-Control
          description: >-
            Send every header listed here with exactly these values on the PUT,
            Cache-Control included. A missing or different header makes the
            upload fail.
        expiresAt:
          type: string
          description: ISO 8601 UTC. The URL is valid for 15 minutes.
      required:
        - uploadId
        - uploadUrl
        - method
        - headers
        - expiresAt
    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
  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
    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.