openapi: 3.1.0
info:
  title: Cloudinary Backup Upload API
  description: The Cloudinary Upload API provides server-side endpoints for uploading, transforming, renaming, and managing assets (images, videos, raw files) in a Cloudinary product environment. Endpoints are versioned under /v1_1/{cloud_name}/{resource_type} and use HTTP Basic Auth with API key and secret.
  version: 1.0.0
  contact:
    name: Cloudinary Support
    url: https://cloudinary.com/contact
  license:
    name: Proprietary
    url: https://cloudinary.com/tos
servers:
- url: https://api.cloudinary.com/v1_1/{cloud_name}
  description: Cloudinary Upload API base
  variables:
    cloud_name:
      default: YOUR_CLOUD_NAME
      description: Your Cloudinary cloud name
security:
- basicAuth: []
tags:
- name: Upload
  description: Asset upload and management.
paths:
  /{resource_type}/upload:
    post:
      operationId: uploadAsset
      summary: Upload an asset
      description: Upload an image, video, or raw file to the product environment.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          enum:
          - image
          - video
          - raw
          - auto
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '200':
          description: Asset uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
  /{resource_type}/rename:
    post:
      operationId: renameAsset
      summary: Rename an asset
      description: Modify the public ID of an existing asset.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          description: Asset renamed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
  /{resource_type}/destroy:
    post:
      operationId: destroyAsset
      summary: Delete an asset
      description: Permanently delete a single asset by public ID.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          description: Asset deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /{resource_type}/tags:
    post:
      operationId: manageTags
      summary: Manage asset tags
      description: Add, remove, or replace tags on existing assets.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          description: Tags updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /{resource_type}/context:
    post:
      operationId: manageContext
      summary: Update contextual metadata
      description: Add or remove contextual metadata key-value pairs on assets.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          description: Context updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /{resource_type}/metadata:
    post:
      operationId: updateMetadata
      summary: Update structured metadata
      description: Update structured metadata fields for one or more assets.
      tags:
      - Upload
      parameters:
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          description: Metadata updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
components:
  schemas:
    GenericResponse:
      type: object
      additionalProperties: true
    GenericRequest:
      type: object
      additionalProperties: true
    Asset:
      type: object
      properties:
        asset_id:
          type: string
        public_id:
          type: string
        version:
          type: integer
        format:
          type: string
        resource_type:
          type: string
        secure_url:
          type: string
          format: uri
      additionalProperties: true
    UploadRequest:
      type: object
      properties:
        file:
          type: string
          description: File data, URL, or base64 encoded payload.
        public_id:
          type: string
        timestamp:
          type: integer
        signature:
          type: string
        api_key:
          type: string
      additionalProperties: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using API key as username and API secret as password.
x-generated-from: https://cloudinary.com/documentation/image_upload_api_reference
x-generated-by: claude-crawl-2026-05-08