Create, list, and read the hierarchical categories that organize a MediaValet library, retrieve the assets filed under a category, and manage category permission sets that govern which users and groups can see and act on each branch of the tree.
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