MediaBeacon API

Authentication

1. Create a key in the UI: log in as the user the integration should act as, open Manage → System Status → API Keys and choose Create API Key S2. Administrators see all keys, the user who last used each one, and expiry dates S9.
2. Or by API: GET|POST /wf/restapi/v2/getApiKey?name=… fetches or creates a key for the authenticated user (default name "REST Api Key"); deleteApiKey removes one, subject to permissions S1.
3. Send it as apikey=<key> in the query string or form body, or in a request header S2. HTTP Basic (Authorization: Basic …) or user/pass parameters also work S2.
4. Choose the ACL: add acl_id=<id> to run under a specific group/ACL; otherwise the user's default ACL is used S2.
5. From workflows: apiKeyManager creates permanent, expiring or workflow-restricted keys, e.g. to hand a narrowly scoped key to an external system S3.

SSO (SAML/IdP) covers interactive log-in only. No token-based federated API authentication is documented S9 S12.

Core resources

REST v2 reference 25.07: 48 documented endpoint pages (some endpoints have one page per HTTP method) S1. The API accepts GET, POST and PUT interchangeably for most endpoints; the admin managers distinguish GET/POST/PUT/DELETE S2 S1. All paths are relative to https://{tenant}.

Legacy REST v1 (/wf/restapi/1/…, 29 documented operations such as search, info, getPreviews, generateContactSheet, pathToAssetId, submitAssets, upload) S5. The doc source paths show that the REST endpoints are themselves packaged as JavaScript workflows ("RESTWorkflows") S5 Unverified (inferred from file names).

Workflow JavaScript API (server-side): 148 class pages, including managers exposed as globals in a workflow context. Documented globals include fileManager, searchManager, fieldManager, dictionaryManager, userManager, groupManager, apiKeyManager, pluginManager, s3Manager, linkManager, versionManager, previewManager, mailManager, notificationManager, savedSelectionManager, loadingDockManager. Other classes cover external sharing, video, metrics and workflow control. Also trigger event/configuration classes, AJAX for outbound HTTP, SQL access to external data sources, and PDF/contact-sheet helpers S3.

Client JS API (browser): publishers for search, selection, metadata (MBAPI.md.batchSetField), download, upload, permissions, notifications, M3TA forms and menus, plus UI events (selection, view, workspace change) S4 S13 S15.

Data model

• Asset: numeric asset ID (also called record ID), file name, managed path, directory ID, width/height, bytes, lastModified (epoch ms), MIME type, previews (thumbnail, viewex preview, downloadUrl servlet links), and optional publishedRenditions (preset name → public S3 URL, renditions licence required) S1 S2.
• Resolver URLs address sets of assets or directories (e.g. directory://182) and can replace an ids array S1 S2.
• Metadata: XMP properties keyed by "<namespace URI> <name>". Values are strings or arrays (multi-value). Repeating data blocks are structured values S1 S9. MediaBeacon-specific namespaces include http://ns.mediabeacon.com/… and a metrics schema S9 S1.
• Directories: {name, path, id, resolver, hasChildren, assets[]} S1.
• Security: users → groups → ACLs. ACL IDs are strings (e.g. 0_6_<GUID>) S2 S9.

Search & querying

• Structured search (/search): a JSON object {conjunction: "and"|"or", criteria: [{fieldId, condition, value}]}. Conditions depend on field type: eq, ne, lt, le, gt, ge, between (dates), cont, not_cont, beg, end, null, not, cont_part, all, any, phrase, wo (without word), anyval, notchanged… S1. A special directory pseudo-field restricts by path S1.
• Saved searches run by savedSearchId S1. Quick search takes a string, optionally limited to a directory S1. Type-ahead returns R3Search suggestions S1.
• Sorting: sortField (field ID or record_id) + sortDirection ASC/DESC S1.
• Facets: /facets?fieldId=… with paging and hierarchyLevel for hierarchical fields S1. Empty / not-empty conditions on asset-link fields arrived in 25.03 S13.
• Post-filters: with verbose=true, responses can be filtered on id, name, path, height, width, bytes, lastModified, mimeType, resolver, using wildcards (test*) and comparisons (bytes=>4095). Filters apply after the operation, so for paging the docs recommend search criteria instead S2 S1.
• Deep pagination: page index only; no cursor or scroll documented; total-count field Unknown.

Uploads & binaries

• Upload: POST/wf/restapi/v2/upload as multipart form data, with the file in field file and a destination dest (path) or destId (directory ID). Options: unzip, version (create a new version if the name exists), message, replaceMetadata, replaceName, metadata (JSON field→value stamped on the new asset), asyncImport, and triggerAssetBasedWorkflow=false to skip "asset added" workflows S1.
• New version: POST/checkIn with id + file. Use /checkOut to lock first S1.
• Server-side import: /import registers files already present in managed storage (paths or IDs) S1.
• Chunked / large files: no chunked REST upload documented. S3-integrated environments use multipart upload internally S15 S13, and the Workflow API AJAX.addBinaryChunk and s3Manager (presigned-URL copy, S3 upload with placeholder asset) cover server-side transfers S3.
• Download: /download?ids=[…] builds a ZIP and answers 302 to the file S1. Per-asset downloadUrl / preview servlet links are in verbose asset data S1. Public S3 rendition URLs appear when renditions are published S1. External share links (expiring, download-counted) are created from workflows with the JSExternalSharingManager class S3.

Events & webhooks

• No outbound webhook subscription API exists in the REST reference S1.
• Equivalent mechanism: server-side workflows with trigger configurations: AssetAdded, AssetModified, AssetMoved, AssetRenamed, AssetCopied, AssetRemoved, AssetDownloaded, AssetCheckin, Permission, Scheduled, UserTriggered S3. They are configured in the Workflow Manager (enable, schedule, client-side triggering, thread count) S9. A workflow can then push to an external endpoint with AJAX; retries and signing are left to the script S3 Unverified (no built-in retry or signature).
• REST uploads can suppress these triggers (triggerAssetBasedWorkflow=false) S1.

Limits & quirks

• GET length 2,048 characters, no files on GET S2.
• Tomcat and brackets: JSON arrays in query strings (ids=[…]) can cause HTTP 400 on Tomcat unless relaxedQueryChars / relaxedPathChars are set on the connector S2.
• Defaults are minimal: without verbose=true, assets come back as IDs only (directories as paths) S2.
• Filters run post-operation and can yield short pages S2.
• Field visibility is form-driven: fields missing from the ACL's forms are silently absent from responses (documented after a 25.03 support case) S13.
• Regression example: a REST le search on metadataModifyTime broke and was fixed in 25.07 S12.
• Workflow defaults: AJAX request timeout 15 s S3.
• Documentation location drift: the official PDF links to a redirected page S21 S6; use the S3-hosted reference (Resources).

SDKs, tools & code samples

No official REST client library, CLI or Postman collection was found S47.

Changelog of the API