openapi: 3.0.3
info:
  title: MediaValet Open API
  description: >-
    The MediaValet Open API is a RESTful, JSON, hypermedia-driven interface to the
    MediaValet cloud digital asset management (DAM) platform. It lets developers and
    partners automate the management of digital assets, categories, attributes,
    keywords, uploads, and users. Requests are made to the API gateway at
    https://api.mediavalet.com and must carry two credentials: an OAuth 2.0 (OIDC)
    Bearer access token obtained from https://login.mediavalet.com/connect/token, and a
    per-account subscription key sent in the Ocp-Apim-Subscription-Key header. Access
    to the API requires a MediaValet subscription and Developer Portal registration.
    The paths documented here are modeled from MediaValet's public developer
    documentation and community SDKs; verify exact request/response schemas against the
    live reference at docs.mediavalet.com.
  version: '1.0'
  contact:
    name: MediaValet
    url: https://www.mediavalet.com
servers:
  - url: https://api.mediavalet.com
    description: MediaValet API gateway (public)
security:
  - oauth2: []
    subscriptionKey: []
tags:
  - name: Assets
    description: Core digital asset objects and their derivatives.
  - name: Categories
    description: Hierarchical folders that organize assets.
  - name: Attributes
    description: Custom metadata fields and their values on assets.
  - name: Keywords
    description: Keyword vocabulary and per-asset tagging.
  - name: Uploads
    description: Chunked ingest of new files into a library.
  - name: Users
    description: Users, groups, and permissions.
paths:
  /search:
    get:
      operationId: searchAssets
      tags:
        - Assets
      summary: Search assets
      description: Search the library for assets matching a query, with pagination and filtering.
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Full-text search query.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of matching assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}:
    get:
      operationId: getAsset
      tags:
        - Assets
      summary: Get an asset
      description: Retrieve a single asset by its identifier, including metadata and rendition links.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The requested asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAsset
      tags:
        - Assets
      summary: Update an asset
      description: Update an asset's editable fields.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Asset'
      responses:
        '200':
          description: The updated asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/relatedassets:
    get:
      operationId: getRelatedAssets
      tags:
        - Assets
      summary: List related assets
      description: List assets related to the given asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: A list of related assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/renditions:
    get:
      operationId: getAssetRenditions
      tags:
        - Assets
      summary: List asset renditions
      description: List the generated renditions (thumbnails, previews, derivatives) for an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: A list of renditions.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/attributes:
    get:
      operationId: getAssetAttributes
      tags:
        - Assets
      summary: Get asset attributes
      description: Retrieve the attribute values applied to an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The asset's attribute values.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/categories:
    get:
      operationId: getAssetCategories
      tags:
        - Assets
      summary: Get asset categories
      description: List the categories an asset is filed under.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The categories for the asset.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/keywords:
    get:
      operationId: getAssetKeywords
      tags:
        - Assets
      summary: Get asset keywords
      description: List the keywords applied to an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The keywords for the asset.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addAssetKeywords
      tags:
        - Assets
      summary: Add keywords to an asset
      description: Add one or more keywords to an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Keywords added.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/keyword/{keyword}:
    delete:
      operationId: removeAssetKeyword
      tags:
        - Assets
      summary: Remove a keyword from an asset
      description: Remove a single keyword from an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
        - name: keyword
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Keyword removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/comments:
    get:
      operationId: getAssetComments
      tags:
        - Assets
      summary: Get asset comments
      description: List comments on an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The asset's comments.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/history:
    get:
      operationId: getAssetHistory
      tags:
        - Assets
      summary: Get asset history
      description: Retrieve the change history / audit trail for an asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The asset's history.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{assetId}/videoIntelligence/status:
    get:
      operationId: getVideoIntelligenceStatus
      tags:
        - Assets
      summary: Get video intelligence status
      description: Retrieve the processing status of AI video intelligence for a video asset.
      parameters:
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: The video intelligence status.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /categories:
    get:
      operationId: listCategories
      tags:
        - Categories
      summary: List categories
      description: List the categories in the library.
      responses:
        '200':
          description: A list of categories.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCategory
      tags:
        - Categories
      summary: Create a category
      description: Create a new category in the library tree.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '201':
          description: The created category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /categories/{categoryId}:
    get:
      operationId: getCategory
      tags:
        - Categories
      summary: Get a category
      description: Retrieve a single category by its identifier.
      parameters:
        - $ref: '#/components/parameters/CategoryId'
      responses:
        '200':
          description: The requested category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /categories/{categoryId}/assets:
    get:
      operationId: getCategoryAssets
      tags:
        - Categories
      summary: List assets in a category
      description: List the assets filed under a category.
      parameters:
        - $ref: '#/components/parameters/CategoryId'
      responses:
        '200':
          description: A list of assets in the category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /categories/permissionSets:
    get:
      operationId: listCategoryPermissionSets
      tags:
        - Categories
      summary: List category permission sets
      description: List the permission sets that govern access to categories.
      responses:
        '200':
          description: A list of permission sets.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attributes:
    get:
      operationId: listAttributes
      tags:
        - Attributes
      summary: List attributes
      description: List the custom attribute (metadata field) definitions in the library.
      responses:
        '200':
          description: A list of attribute definitions.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAttribute
      tags:
        - Attributes
      summary: Create an attribute
      description: Create a new custom attribute definition.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attribute'
      responses:
        '201':
          description: The created attribute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attributes/{attributeId}:
    get:
      operationId: getAttribute
      tags:
        - Attributes
      summary: Get an attribute
      description: Retrieve a single attribute definition by its identifier.
      parameters:
        - name: attributeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested attribute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /keywords:
    get:
      operationId: listKeywords
      tags:
        - Keywords
      summary: List keywords
      description: List the keyword vocabulary for the library.
      responses:
        '200':
          description: A list of keywords.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createKeyword
      tags:
        - Keywords
      summary: Create a keyword
      description: Add a new keyword to the library vocabulary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Keyword'
      responses:
        '201':
          description: The created keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Keyword'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /keywords/{keywordId}:
    get:
      operationId: getKeyword
      tags:
        - Keywords
      summary: Get a keyword
      description: Retrieve a single keyword by its identifier.
      parameters:
        - name: keywordId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Keyword'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /keywordGroups:
    get:
      operationId: listKeywordGroups
      tags:
        - Keywords
      summary: List keyword groups
      description: List the keyword groups that organize the keyword vocabulary.
      responses:
        '200':
          description: A list of keyword groups.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploads:
    post:
      operationId: createUpload
      tags:
        - Uploads
      summary: Create an upload session
      description: >-
        Create an upload session for a new file. The response returns the storage
        location and identifiers used to transfer file chunks and, once all chunks
        are transferred, to commit the upload for processing into an asset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '201':
          description: The created upload session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /uploads/{uploadId}:
    get:
      operationId: getUpload
      tags:
        - Uploads
      summary: Get an upload session
      description: Retrieve the status of an upload session.
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The upload session status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: commitUpload
      tags:
        - Uploads
      summary: Commit an upload session
      description: >-
        Commit a completed upload session so MediaValet processes the transferred
        file into a managed asset with generated renditions.
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: The upload was accepted for processing.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List users
      description: List the users in the organization.
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/current:
    get:
      operationId: getCurrentUser
      tags:
        - Users
      summary: Get the current user
      description: Retrieve the profile of the authenticated user.
      responses:
        '200':
          description: The current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/current/permissions:
    get:
      operationId: getCurrentUserPermissions
      tags:
        - Users
      summary: Get the current user's permissions
      description: Retrieve the effective permissions of the authenticated user.
      responses:
        '200':
          description: The current user's permissions.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/approvers:
    get:
      operationId: listApprovers
      tags:
        - Users
      summary: List approvers
      description: List the users who can approve requests within the organizational unit.
      responses:
        '200':
          description: A list of approvers.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups:
    get:
      operationId: listUserGroups
      tags:
        - Users
      summary: List user groups
      description: List the user groups in the organization.
      responses:
        '200':
          description: A list of user groups.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0 / OpenID Connect. Obtain an access token from
        https://login.mediavalet.com/connect/token using the authorization code flow
        (interactive apps) or password / client-credential grants, with scopes
        openid api offline_access. Send the token as a Bearer Authorization header.
      flows:
        authorizationCode:
          authorizationUrl: https://login.mediavalet.com/connect/authorize
          tokenUrl: https://login.mediavalet.com/connect/token
          scopes:
            openid: OpenID Connect identity
            api: Access the MediaValet API
            offline_access: Obtain a refresh token
    subscriptionKey:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Per-account API subscription key issued through the MediaValet Developer Portal.
  parameters:
    AssetId:
      name: assetId
      in: path
      required: true
      description: The unique identifier (UUID) of the asset.
      schema:
        type: string
        format: uuid
    CategoryId:
      name: categoryId
      in: path
      required: true
      description: The unique identifier (UUID) of the category.
      schema:
        type: string
        format: uuid
  responses:
    Unauthorized:
      description: Authentication failed - missing or invalid access token or subscription key.
    NotFound:
      description: The requested resource was not found.
  schemas:
    Asset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        title:
          type: string
        description:
          type: string
        mediaType:
          type: string
          description: The kind of media, e.g. image, video, document.
        createdDate:
          type: string
          format: date-time
        modifiedDate:
          type: string
          format: date-time
    AssetList:
      type: object
      properties:
        totalCount:
          type: integer
        offset:
          type: integer
        count:
          type: integer
        payload:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
    Category:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        parentId:
          type: string
          format: uuid
        assetCount:
          type: integer
    Attribute:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          description: The data type of the attribute, e.g. text, number, date, list.
    Keyword:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        keywordGroupId:
          type: string
          format: uuid
    Upload:
      type: object
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        status:
          type: string
          description: The processing status of the upload session.
        storageLocation:
          type: string
          description: The location to which file chunks are transferred.
    UploadRequest:
      type: object
      required:
        - filename
      properties:
        filename:
          type: string
        fileSize:
          type: integer
          format: int64
        categoryId:
          type: string
          format: uuid
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        role:
          type: string