Acquia DAM (ex-Widen) API

Authentication

Personal access token S1 S6

• Generated in the DAM application under Admin → Global Settings → API Setup; it inherits the permissions of the user who generated it.
• Sent as Authorization: Bearer <token> (preferred) or Authorization: Basic base64(<token>:x-oauth-basic).

OAuth 2.0 (third-party apps) S1 S7

1. Client ID (format …app.widen.com) and secret are obtained out of band from Acquia (Widen) support; there is no self-service app registration.
2. Redirect the user to https://{tenant}.widencollective.com/allowaccess?client_id=…&redirect_uri=…&state=… (state optional). The user signs in if needed and approves the client on an "Allow Access" page.
3. Acquia DAM redirects to redirect_uri with code (prefix wac_) and state.
4. POSThttps://api.widencollective.com/v2/oauth/access-token with JSON {client_id, client_secret, grant_type: "authorization_code", authorization_code} — no other auth needed. Response: access_token, token_type: "Bearer", plus refresh_token and expires_in (seconds) when the client uses refresh tokens.
5. Refresh: same endpoint with grant_type: "refresh_token" and refresh_token (prefix wrt_); a new refresh token is returned and the old one is consumed.

Revocation S1 S6: DELETE/v2/oauth/access-token invalidates the calling token (v1: POST/api/rest/oauth/logout); deleting the user or disabling the integration also disables its tokens.

Token prefixes seen in vendor examples: wat_ access token, wac_ authorization code, wrt_ refresh token S1.

Core resources

v2 paths are relative to https://api.widencollective.com; v1 paths to https://{tenant}.widencollective.com. Inventory parsed from the specs S1 S3.

Not exposed in the documented API (checked against both specs S1 S3): user/role/group administration, SSO configuration, portal management, metadata field creation (only vocabulary values), saved searches, Templates. Whether more exists behind feature toggles is Unknown.

Data model

S1 unless noted.

• Asset — identified by a UUID id; also external_id, version_id, current_version, filename, created_date, last_update_date, file_upload_date, deleted_date, released_and_not_expired, _links. Dates are ISO-8601; list indices 0-based.
• Metadata — metadata.fields is a map of field display key → array of strings (e.g. {"keywords": ["…"], "description": ["…"]}). Display keys never change, unlike display names, so integrations should use them S11. The metadata_info expand returns the asset's metadata type (field_set) and its fields with field_type, controlled_vocabulary, editable, required S1. Each asset has exactly one metadata type, assigned at upload S27.
• Field types in the API: selection_list, selection_list_multi, text, text_multi_line, date, numeric, checkboxes… S1; UI families: date, numeric, limited text (255 chars), text (1,280 chars), text area/long text, checkbox, dropdown (UI shows up to 249 values), autocompleter, palette S27.
• Security — asset_groups[] (every asset needs at least one), release_date, expiration_date S1 S18.
• Taxonomy — hierarchical categories addressed by path (slashes in names escaped as %5C%2F), collections (global/private/shared), human tags and machine ai_tags (both added to API responses in June 2026 S31).
• Files — file_properties (format, format_type, size_in_bytes, image/video properties); thumbnails (signed URLs with valid_until, URL syntax not guaranteed); embeds (named CDN renditions such as original, 640px-landscape); status.upload_progress ∈ pending, verifying, complete.
• Products (Entries) — products with typed attributes (text, rich_text, asset, single_controlled_vocab, multi_controlled_vocab), attribute groups, product types, categories, parent/variant links, channels.

Search & querying

Uploads & binaries

Single request S1 — POST/v2/uploads (multipart/form-data): profile (upload profile name, required: profiles set initial metadata and security), one of file | url (public URL to fetch) | file_id (from a chunked upload), optional filename and metadata (JSON in the Update Metadata format).

Chunked upload S1 S6

1. POST/v2/uploads/chunks/start → session_id, valid 7 days.
2. POST/v2/uploads/chunks/upload per part: session_id, chunk_number (1–10,000), file (5 MB minimum except the last chunk, 100 MB maximum) → returns a tag. Up to 40 concurrent chunk operations S6.
3. POST/v2/uploads/chunks/complete with all tags → file_id; POST/v2/uploads/chunks/status to check progress.
4. POST/v2/uploads with file_id to create the asset. Some accounts do not have chunked upload enabled (error message tells you to contact support) S1.

v1 upload — POST/api/rest/asset (uploadProfileUUID, file, filename) is limited to 5 GB; larger files and chunking require v2 S3.

After upload, poll GET/v2/assets/{id}?expand=status until upload_progress is complete before relying on embeds and previews S1. A new version of an existing asset cannot be uploaded through any documented v2 or v1 endpoint; version history is read-only and requires the AssetVersioning feature on the site S1 S3 Unverified (absence inferred from the specs).

Downloads & renditions S1 S3

• embeds expand: CDN URLs (embed.widencdn.net) for the original and configured sizes; these links are served by the CDN and are not counted against the rate limit S1.
• Custom renditions follow a URL convention documented in the help center (size, crop, format parameters); "templated" embed URLs are deprecated S1.
• thumbnails expand: short-lived signed URLs (125–2048 px) S1.
• v1 orders package assets (with conversions) into a ZIP: POST/api/rest/order → POST/api/rest/order/uuid/{uuid}/zip → poll GET…/zip for the link S3.

Events & webhooks

Asset webhooks S1 S12 S13

• Prerequisites: an admin enables the webhook feature (Admin → Global Settings → Features, "Integrate" section) and grants the role permission "Administrate Webhooks" S13.
• Managed only through the API: POST/v2/webhooks/configurations with delivery_url, event_type, optional secret_key (≤ 256 chars) and, for metadata-value events, optional monitored_metadata_fields (display keys; 403 if the user cannot see a field) S1.
• Event types (9): asset_created, asset_deleted, asset_version_added, asset_categories_updated, asset_tags_updated, asset_asset_groups_updated, asset_release_date_updated, asset_expiration_date_updated, asset_metadata_value_updated S1. The metadata-value event was added in June 2026 S31.
• Payload (e.g. asset_created): webhook_configuration_id, webhook_delivery_id, event context (acting user), asset_id, event_type, date_created S12; update events add a change object, deletions a date_deleted S1 (spec examples). TypeScript event types ship in the SDK S15.
• Signing: if a secret key is set, every delivery carries an HMAC hex-digest signature (signing_enabled: true on the configuration) S1 S12. The header name and hash algorithm are not stated in the public docs — Unknown.
• Testing: GET/v2/webhooks/configurations/{id}/ping; configurations expose delivery_enabled, last_delivered_date, last_pinged_date S1.
• Retries, ordering and delivery guarantees: Not public.

Workflow webhooks S1 — POST/v2/workflow/webhooks with event ∈ PROJECT_CREATED, DELIVERABLE_STATUS_CHANGED and a target URL; list and delete endpoints; no signing documented.

Native automations — Acquia also uses webhooks internally for event-driven "task automation" integrations (August 2026) S32.

Limits & quirks

• Monthly API call allowance (billing). For Workgroup plans, calls not authorized through an Acquia OAuth client are capped at 500,000/month (1,000,000 with Entries); overages are billed, Acquia-managed and authorized third-party integrations are excluded S18. The pricing page lists 500k (Workgroup), 1M (Mid-Market) and "Standard API access" (Enterprise) S19. The FAQ says the allowance applies to customers who joined from 2022-04-01 and Entries adds 500,000 calls S6 S8. There is no service interruption when exceeded S8. Unverified The v2 spec still says the 50 calls/s rate is "the only limitation" S1 — true for throttling, but not for billing.
• Rate limit history: raised from 10 to 50 calls/s in February 2022 S36.
• Swapped parameter descriptions: in the v2 spec, include_archived is described as returning deleted assets and include_deleted as returning archived ones S1 Unverified (documentation bug; actual behaviour not tested).
• Inconsistent token examples: the security-scheme examples use an authorization-code prefix (wac_…) as a bearer token, while the intro uses wat_… S1.
• Split surface: category/collection creation and membership, orders, embed-code generation, integration links and metadata-type changes remain v1-only S1 S3; the official SDK therefore calls both versions and needs the tenant key for v1 S15.
• Offset ceilings: search offset ≤ 10,000 S9; collections and products list offset ≤ 9,999 in the schema S1.
• Security update caveat: PUT/v2/assets/{id}/security with patch=all nulls any property not sent; an asset left without security values becomes unavailable S1.
• Metadata search by display name breaks when admins rename a field — use display keys S11.
• Chunked upload limits: 5–100 MB per chunk, 10,000 chunks, session 7 days S1. UI uploads are limited to 500 GB per file S26.
• API access is licensed: "REST API" is an add-on in the product guide and the MCP server requires the REST API feature S18 S14.

SDKs, tools & code samples

No official Python, PHP (outside Drupal), Java or .NET SDK was found S15 S79.

Changelog of the API