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

# Upload asset

> Uploads a single file. Send the request as `multipart/form-data` with the file in the `file` field. To upload several files at once, use [Bulk upload assets](/api-reference/assets/bulk-upload-assets).



## OpenAPI

````yaml openapi.json POST /api/v1/assets
openapi: 3.0.3
info:
  title: Media Cloud API
  version: 1.0.0
  description: >-
    Upload, list, fetch and delete media assets on Media Cloud.


    All routes are mounted under `/api/v1` and authenticated with an API key
    sent as a Bearer token. Responses use the JSON:API media type,
    `application/vnd.api+json`: a resource is `{ id, type, attributes }` inside
    a `data` member, and lists add `links` and `meta` for pagination.
  contact:
    name: Media Cloud
    url: https://mediacloud.me
servers:
  - url: https://api.mediacloud.me
    description: Media Cloud API
security:
  - bearerAuth: []
tags:
  - name: Assets
    description: Upload, retrieve, trash and permanently delete files.
paths:
  /api/v1/assets:
    post:
      tags:
        - Assets
      summary: Upload asset
      description: >-
        Uploads a single file. Send the request as `multipart/form-data` with
        the file in the `file` field. To upload several files at once, use [Bulk
        upload assets](/api-reference/assets/bulk-upload-assets).
      operationId: uploadAsset
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload.
      responses:
        '201':
          description: The asset was created.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AssetResource'
              example:
                data:
                  id: 01a0bfc8-04c4-73c6-9871-81930cdc3f18
                  type: assets
                  attributes:
                    name: Bonusantragstellung_MA-Empfehlung_EN.docx
                    type: document
                    extension: docx
                    mime_type: >-
                      application/vnd.openxmlformats-officedocument.wordprocessingml.document
                    size: 35279
                    folder_id: null
                    created_at: '2026-09-20T17:05:51.000000Z'
                    updated_at: '2026-09-20T17:05:51.000000Z'
                    width: null
                    height: null
                    duration_seconds: null
                    optimized_size: null
                    is_favourite: null
                    status: ready
                    public_file_id: f1f12690-2fb7-4c4f-b3c4-d344b495b089
                    url: >-
                      https://api.mediacloud.me/api/v1/files/f1f12690-2fb7-4c4f-b3c4-d344b495b089/content
                    thumbnail_url: null
                    download_url: >-
                      https://api.mediacloud.me/api/v1/files/f1f12690-2fb7-4c4f-b3c4-d344b495b089/download
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AssetResource:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Asset'
    Asset:
      type: object
      description: A JSON:API resource object for a stored file.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the asset.
        type:
          type: string
          enum:
            - assets
          description: The JSON:API resource type.
        attributes:
          $ref: '#/components/schemas/AssetAttributes'
    AssetAttributes:
      type: object
      properties:
        name:
          type: string
          description: The file name.
        type:
          type: string
          description: The asset category, for example `image` or `document`.
        extension:
          type: string
          description: The file extension detected for the stored file.
        mime_type:
          type: string
          description: The MIME type detected for the stored file.
        size:
          type: integer
          description: File size in bytes.
        folder_id:
          type: string
          nullable: true
          description: >-
            The containing folder's id, or `null` when the asset is not in a
            folder.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        width:
          type: integer
          nullable: true
          description: Width in pixels. `null` for non-visual files.
        height:
          type: integer
          nullable: true
          description: Height in pixels. `null` for non-visual files.
        duration_seconds:
          type: number
          nullable: true
          description: Duration in seconds for audio and video. `null` otherwise.
        optimized_size:
          type: integer
          nullable: true
          description: Size in bytes of the optimized version, when one exists.
        is_favourite:
          type: boolean
          nullable: true
          description: >-
            Whether the asset is marked as a favourite. `null` on responses to
            uploads.
        status:
          type: string
          description: Processing status. `ready` means the asset can be served.
          example: ready
        public_file_id:
          type: string
          format: uuid
          description: Identifier used in the asset's file URLs.
        url:
          type: string
          format: uri
          description: URL that serves the file content.
        thumbnail_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL of the thumbnail variant. `null` when the asset has no
            thumbnail.
        download_url:
          type: string
          format: uri
          description: URL that downloads the file.
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a Bearer token: `Authorization: Bearer YOUR_API_KEY`.'

````

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