MediaValet API

Authentication

Getting credentials S5 S21 S22

1. Have a user (ideally admin) account in the MediaValet library to integrate with.
2. Register at the developer portal (developer.mediavalet.com, Azure APIM) and subscribe to a plan under Products — the Developer Plan is included in the MediaValet subscription; the Enterprise Plan goes through the account manager.
3. MediaValet Support e-mails you to collect the library URL, redirect URIs to whitelist and (if you are not an admin) an admin's approval; it then issues client_id / client_secret and activates the primary/secondary subscription keys visible in your portal profile.
4. Postman callback URLs (https://www.getpostman.com/oauth2/callback, https://oauth.pstmn.io/v1/callback, https://oauth.pstmn.io/v1/browser-callback) are whitelisted by default; other redirect URIs must be whitelisted by Support. Credentials may be shared by several users of the same library working on the same integration S22.

Endpoints S1 S14

Authorization code flow S1: /connect/authorize?client_id=…&response_type=code&scope=openid api&redirect_uri=…&state=… → user signs in on MediaValet's login page → code returned to the redirect URI → server-side POST/connect/token with grant_type=authorization_code, code, redirect_uri, client_id, client_secret → response {id_token, access_token, expires_in: 3600, token_type: "Bearer"}. Use Authorization: Bearer <token> on API calls.

Resource owner password grant S1 S16: POST/connect/token with grant_type=password, username, password (the user's DAM login), scope=api (or openid api), and Authorization: Basic base64(client_id:client_secret). MediaValet discourages it for security reasons but calls it the preferred option for non-interactive integrations; the official GitHub sample uses only this flow.

Refresh S1: grant_type=refresh_token + client credentials; returns new access_token, id_token and a new refresh_token.

Every API request also needs the APIM subscription key: without it the gateway answers 401 with WWW-Authenticate: AzureApiManagementKey … name="Ocp-Apim-Subscription-Key" S15; the Unify API description states both the IAM JWT and the subscription key are mandatory S12.

Unverified Grant-type inconsistencies. The docs' parameter table lists only authorization_code and refresh_token as grant types, the same page documents the password grant, the Help Center lists "Auth Code + Resource Owner Password" and says Client Credentials is "COMING SOON" S1 S23, while the public OIDC discovery document advertises client_credentials, implicit, device_code, CIBA and token-exchange grants and PKCE (S256, plain) S14. Discovery reflects the identity server's capabilities, not necessarily what is enabled for API clients — treat client credentials and PKCE as not officially supported until documented. Scopes advertised in discovery include api:service_principal, iam.admin and iam.provisioning (undocumented) S14.

Core resources

Paths are relative to https://api.mediavalet.com. Counts are APIM operations (NextGen API) per first path segment S9; examples from the Postman collection S2.

Rights/usage and workflow resources: no dedicated endpoints beyond asset status/approval fields, expiry dates (expiresAt), lightboxes for approval and download requests S2; proofing (PageProof) and templating (Marq) have no public API documented here (Unknown).

Data model

• Envelope on every response: ApiVersion, Meta {MetaInformation, Warnings[], Errors[], CreatedOn}, RecordCount {TotalRecordsFound, StartingRecord, RecordsReturned}, Payload S1.
• Asset (GUID id) with title, a media block of pre-signed URLs per rendition (thumb, small, medium, large, original, download, stream/streamingManifest) carrying sasExpiry/sasRenewal, and a file block (fileName, md5, fileType, sizeInBytes, uploadedAt, approvedAt, expiresAt, dimensions, video bitrate/frame rate, mimeType, colorMode…) S2.
• Asset status codes used in filters: 0 approved, 2 pending, 5 rejected, 7 expired, 9 checked out S1; upload finalisation sets status 1 (ready for processing) S2.
• Taxonomy: categories (tree, CategoryIds / CategoryAncestorIds), lightboxes, keywords (inside keyword groups, with approval status) and attributes (custom fields, grouped; data types incl. Status) S1 S2.
• Libraries belong to an organizational unit; libraryId appears in public routes and in webhook payloads S2 S1.
• Since v1.2 the asset DTO returns permissions as an array like other resources S1.

Search & querying

• Full text: GET/assets?search=… (or body of POST/assets/search) across categories, keywords, file names, comments, descriptions; implicit AND, explicit AND/OR/NOT, "exact phrase", * wildcards S1.
• Field-scoped search: field prefixes or searchFields= among categoryIds, category(ies), cognitiveBackgroundColor, cognitiveForegroundColor, cognitiveDominantColors, cognitiveTextInImage, comments, description, fileName, keywords, title; the POST body also accepts cognitiveContentInDocument, cognitiveTags, videoIntelligence S1 S2.
• Filters: filters= with EQ NE LT GT LE GE CT SW EW, AND/OR, parentheses; case-insensitive names and values; filterable: AssetType, attribute values, AverageRating, CognitiveColor (12 colours), CreatedBy, DateApproved/CheckedOut/PendingApproval/Rejected/Uploaded, file extension, Status, CognitiveTextInImage. Filters apply before search S1.
• Container filters: containerFilter=(CategoryIds/ANY(c: c EQ '<id>')), add CategoryAncestorIds/ANY(…) for sub-categories, LightboxIds/ANY(…) for lightboxes (OData-like lambda syntax) S1.
• Semantic / visual: POST/assets/search accepts useSemanticSearch, semanticSearchSimilarity, useRrf (rank fusion) and fileId/fileUrl/fileSearchExactMatch (search by image) S2 — undocumented beyond the request schema Unverified.
• Sorting: e.g. sort=record.createdAt D S2. Facets: GET/search/facets returns counts by file extension only (other facets "planned") S1.
• include, exclude, max-length query parameters are described but marked "not implemented yet" S1.
• Deep pagination limits / maximum count: Not public.

Uploads & binaries

Documented four/five-step flow S1 S2:

1. POST/uploads { "filename": "…" } → holding asset record (status "Uploading") + uploadUrl, an Azure Blob SAS URL with temporary write access.
2. PUT{uploadUrl} with the bytes (x-ms-blob-type header) directly to Azure Blob Storage.
3. PUT/uploads/{assetId} with filename, title, description, fileSizeInBytes (required to be the original size).
4. POST/uploads/{assetId}/categories (assign at least one category; keywords, attributes, lightboxes have sibling endpoints).
5. PATCH/uploads/{assetId} JSON Patch [{"op":"replace","path":"/status","value":1}] → pre-flight validation, rename handling, processing (thumbnails, AI).

• Single PUTs are limited to roughly 64 MB; larger files must be sent in blocks with the Azure Storage SDKs (C# sample provided) S1 S16.
• New versions: check-out / check-in flow (see Core resources) with priority=high on the final PUT in the guide S2.
• Downloads: rendition URLs in the asset media block are SAS-signed and expire (sasExpiry) S2; download jobs via /downloads; persistent public URLs via direct links (POST/directlinks/{assetId} with RenditionSettings size/format and LinkSettings incl. IsUniqueLink, IsEmbedCode) S2. UI-side CDN transformations (AVIF/WebP auto-format, resize ≤ 2,000 px) are documented for the UI S65; their URL syntax is Not public.

Events & webhooks

• Service: SkyHOOK, https://api.mediavalet.com/skyhook, separate APIM API with its own subscription requirement S8 S10.
• Events (8): Asset.StatusUpdated, Asset.MediaFileAdded, Category.AssetsAssigned, Category.AssetUnassigned, Asset.KeywordsAdded, Asset.AttributesAdded, Asset.VideoRenditionsAdded, Asset.KeywordRemoved S1 S25. Asset.StatusUpdated fires on statuses such as Activated, PendingApproval(WithAnnotations), Approved, Rejected, Expired, Deleted, SoftDeleted, CheckedOut S28. No user, portal, CDN-link or deletion-specific events.
• Configuration: by API only — POST/skyhook/subscriptions with Events[], Type = webhook (Data.webhook URL) or eventgrid (Data.eventGridTopicEndpointUrl + eventGridKey); PUT to change events; one subscription per webhook URL (a second one with the same URL fails with 400 "subscription found with similar data") S1 S27.
• Validation: CloudEvents 1.0 webhook abuse-protection handshake — an HTTP OPTIONS request; answer synchronously with WebHook-Allowed-Origin (and WebHook-Allowed-Rate) headers or asynchronously by calling WebHook-Request-Callback; failure leaves the subscription in status Failed S1 S26.
• Payload: CloudEvents JSON (id, source, type, time, specversion: "1.0", subject like /library/{libraryId}/assets/{assetId}/Asset.StatusUpdated, data with LibraryId, AssetId and event specifics; Asset.MediaFileAdded carries a MediaFileBlobUrl) S1.
• Signature / retries: no payload signature or retry policy documented (Unknown).

Limits & quirks

• Two credentials on every call (bearer token + APIM subscription key) — the most common onboarding pitfall; the subscription key is tied to the developer-portal plan, OAuth clients are issued manually by Support S1 S21 S15.
• Manual onboarding: no self-service client creation; redirect URIs are whitelisted by Support S22.
• Admin-centric: the developer portal says an administrator account is needed to use the API S5.
• Documentation drift: 64 APIM operations (metadata import/export/update jobs, metadata templates, external uploads, quick links, IAM clients, experience-portal search, duplicate search…) are absent from the Postman collection S2 S9; the docs changelog stops at v1.2 (2025-06-13) S1; the developer-portal "API changelog" page is not readable without JavaScript.
• Changelog dates use US MM/DD/YYYY format in the docs (e.g. "03/06/2024" = 2024-03-06) Unverified interpretation based on ordering.
• 401 vs 403: from v1.2, missing permission → 403; on v1.0/1.1 it remains 401 S1.
• Facets limited to file extensions; include/exclude/max-length not implemented S1.
• Gateway: api.mediavalet.com is fronted by Cloudflare and Azure APIM S15; the APIM backend reported for the NextGen API is a regional host (api-usca.mediavalet.net) S12 — whether other regions use other backends is Not public.
• Upload size: ~64 MB per single blob PUT; Azure block upload beyond S1.
• Duplicate detection at upload (UI) does not apply to API uploads S30.
• Rate-limit headers / 429 behaviour: Not public.

SDKs, tools & code samples

No official SDK packages on npm, NuGet, PyPI or Packagist S18. Community libraries: none found.

Changelog of the API