DAM Wiki

Brandworkz API

Brandworkz Ltd · London, UK · Founded 1997 · subsidiary of Spinakr Solutions LLC (USA)Verified 2026-10-01 · 66 sources
  • SaaS
  • Mid-market to enterprise
  • REST API
  • SAML SSO
Complete · 7 of 7 pages
66sources
2API specs
10-01verified 2026
Official website ↗Brandworkz alternatives →

Scope: the public Brandworkz API (the vendor's "Java API", documented as v1.6, v1.7 in production) used by the main Brandworkz platform, plus the small Brandworkz Essentials API of the free brand-kit product. Both are documented only as public Postman collections. API access is listed as an Enterprise-plan feature S12.

At a glance

API styles
REST/JSON over HTTPS ("open RESTful/JSON API", service-oriented / micro-services); HTTP requests get a 301 to HTTPS; some endpoints can return HTML (format parameter or Accept header) S1. No GraphQL, SOAP or WebDAV found
Base URL(s)
Discovery: GEThttps://api.brandworkz.com/getAPIURL?clientURL={tenant}.brandworkz.com (always on this global host, for staging or live, any region) returns api_url, client_id, version S1. Functional calls: {api_url}/v{api_version}/{client_id}/{endpoint}; the doc example returns api_url = https://us-api.brandworkz.com S1. OAuth endpoints are unversioned: {api_url}/oauth/token, {api_url}/oauth/authorize S1. Essentials API: https://main-api.brandworkz.com/… S3 S9
Current version(s) & deprecations
Docs titled v1.6 (published 2023-03-29) S1. v1.7 went to production on 2025-01-18 with potentially breaking search and album changes; three album endpoints removed S5. Unverified The public collection was still labelled v1.6 on 2026-10-01 and still lists the removed endpoints — see Changelog of the API. getAssetMetadata is deprecated in favour of /metadata/asset S1. The vendor insists api_url, client_id and version must never be hard-coded because versions are retired S1 S5
Auth methods
OAuth 2.0 with JWT access tokens: password grant (consumer ID/secret via HTTP Basic + a Brandworkz user's login/password) or authorization code flow (mandatory when the site has SAML SSO users); Authorization: Bearer on calls S1. Essentials API: API key sent as Authorization: Bearer {API_KEY} S3
Token lifetime / refresh
expires_in = 1,200 s in the documented example; renew with the refresh_token grant S1. Whether 1,200 s is a fixed value is not stated Unverified
Scopes / permission model
Token response shows scope: "read write"; the code flow requests scope=read S1. Effective rights are those of the Brandworkz user (permission-aware endpoints; user-admin/sysadmin endpoints) S1
Official spec
Postman Collection v2.0.0 "Brandworkz API (v1.6)": 159 requests, 10 folders S1 rendered at apidocs.brandworkz.com S2; "Brandworkz Essentials API": 5 requests S3 S4. Archived copies on DAM Wiki: API spec downloads. No OpenAPI file found, although the G-Cloud listing names OpenAPI (Swagger) among documentation formats S58 Unverified
Rate limits
Not public (no limit, header or 429 documented) S1
Pagination
Varies by endpoint: simpleSearch from (zero-based offset) + size (default 50, max 500); folder listings start + numberOfResults or page + resultsPerPage; user messages limit + offset S1
Webhooks / events
Unknown: no webhook documentation; importAsset accepts an undocumented webhookId S1. Polling alternative: getModifiedResources (modified or deleted between two dates) S1
Official SDKs
None. GitHub bwkz/assetInsert-integration-examples (jQuery, ES6+Webpack; 2019) S6 S7
Sandbox / trial access
Customers have a staging site (QA) besides live; staging access through the account manager S1 S5. Consumer ID/secret come from the customer's Brandworkz contact; no self-service developer signup S1. G-Cloud lists a sandbox/test environment S58

Authentication

Step 1 — discover the API host S1

  • GEThttps://api.brandworkz.com/getAPIURL?clientURL={tenant}.brandworkz.com (staging or live site URL) → { "result": {code, message}, "data": { "api_url", "client_id", "version" } }.
  • Without clientURL the endpoint answers HTTP 400 S8.
  • client_id here is the site's database identifier (example brandworkz_{tenant}), not the OAuth client S1.

Step 2a — password grant (server-side integrations) S1

  • POST{api_url}/oauth/token, HTTP Basic consumer_id:consumer_secret, form body grant_type=password&client_db={client_id}&username=…&password=….
  • Response: access_token (JWT), token_type: bearer, refresh_token, expires_in, scope, plus cdb (site DB), uid (user ID), sid, jti.
  • The user must be an existing user of the site; integrations therefore usually run as a dedicated Brandworkz user (inference Unverified).

Step 2b — authorization code (interactive; required with SAML SSO users) S1

  1. Redirect the browser to {api_url}/oauth/authorize?clientDb={client_id}&response_type=code&client_id={consumer_id}&scope=read&redirect_uri=….
  2. The user logs in on the Brandworkz login form and clicks Authorize on an approval screen (Deny → error=access_denied).
  3. Exchange the code: POST{api_url}/oauth/token with Basic consumer credentials and grant_type=authorization_code&client_db=…&code=…&redirect_uri=… (note client_db here vs clientDb in step 1).
  • PKCE: not documented (Unknown). Client-credentials grant: not documented.

Step 3 — call the API with Authorization: Bearer {access_token}; refresh with grant_type=refresh_token S1.

Session login (legacy/UI): POST/login (with isIntegration=1) and GET/logout create and end a session for a user S1.

Essentials API: API keys are created and managed in Essentials Organisation Settings; all calls over HTTPS with Authorization: Bearer {API_KEY}; errors 403 Access Denied / 400 Bad Request / 500 S3. Unauthenticated calls get a JSON 403 access-error S9.

Core resources

Paths are relative to {api_url}/v{api_version}/{client_id}. Counts per Postman folder from the collection S1.

Resource (folder, # requests)Main endpointsNotes
Assets (35)GET/getAssets, GET/getCategoryAssets, POST/createUploadPath, POST/assemble, POST/importAsset, GET/moveAssets, GET/copyAssets, GET/deleteAssets, GET/setAssetsStatus, GET/relateAssets, GET/getAssetThumbnails, GET/getDownloadOriginalLinks, GET/getEmbedLink, GET/getAssetRendition, GET|POST /assets/permissions, GET/transforms, GET/getUsage, GET/assets/{assetIds}/dependenciesMany write operations are GETs with query parameters; older calls take sequential IDs, newer ones GUIDs. getAssetRendition only returns links for users with the CI HUB integration enabled
Metadata (8)GET/metadata/asset, POST/saveMetadata, GET/getEmbeddedMetadata, GET/metadata/user, GET/metadata/user/{id}, GET/user/metasets, GET/getAlbumAssetMetadata, GET/getAssetMetadata (deprecated)saveMetadata body: assetGuid (required), title, status, publish/expiry dates, languageCode, metasetRef, metadata{systemRef: value}
Search (6)GET/simpleSearch, POST/search, GET/search/definition, POST/createSavedSearch, GET/getSavedSearches, GET/deleteSavedSearchesPOST/search accepts a native Elasticsearch query; user permissions are injected server-side
Categories / folders (16)GET/getCategoryInfo, GET/getSubCategories, GET/getCategoryListing, GET/createCategory (with a/b/c path creation), GET/moveCategory, GET/deleteCategory, GET/categories/permissions, GET/getModifiedResources, GET/getResourcesPageRoot category: getCategoryInfo?categoryID=0. Folders and CMS web pages are both categories
Albums (21)GET/getAlbums, POST/createAlbum, POST/saveAlbum, POST/duplicateAlbum, GET/addAlbumAssets, GET/removeAlbumAssets, GET/getAlbumAssets, POST/shareAlbum, GET/getAlbumHistory, GET/getAlbumSentLogsv1.7: album IDs become UUID4; createAlbumShortLink, getAlbumGlobalTransforms, getAlbumSentEntry removed; new getAlbumAssetDownloadOptions, getAssetDownloadOptions, updateAlbumAssetDownloadOptions S5
Annotations (5)POST/createAnnotation, GET/getAnnotations, GET/updateComment, GET/deleteAnnotation, GET/getWorkflowAnnotationPreviewsTied to asset versions and workflow stages
CMS (20)/cms/page/{categoryGuid} (POST/DELETE), /cms/page/duplicate/…, /cms/templates (CRUD), /cms/templateWidgets/…, /cms/widgetInstances/{guid} (GET/PUT), /cms/widget/codePreview…Brand-guidelines pages, templates and widget ("block") instances
Navigation (11)GET/treeNavigation, GET/albumTreeNavigation, GET/getBreadcrumb, /cms/masthead (CRUD + category assignment), POST/mastheadNavigationMenus and breadcrumbs
Users & groups (26)GET/users, POST/users/create, PUT/users/{userId}/edit, DELETE/users/{userId}/delete, GET/groups, GET/createGroup, GET/users/profile, GET/myStuff, POST/login, GET/logout, POST/users/password/validateusers/create sets login type (internal/SSO), groups and admin flags (sysadmin, users, groups, metadata, transforms, workflow, reports…)
Integration (11)GET/assetInsert, GET|POST /integrations, PUT/integrations/{guid}, PUT/integrations/{guid}/parameters, POST/integrations/{guid}/enable|disable, GET/integrations/types, GET/integrations/templates, GET/integrations/{guid}/auditassetInsert returns an embeddable search/browse picker (see below)
Renditions / transformsGET/transforms, GET/getCategoryTransforms, GET/getAlbumTransforms, GET/getEmbedLink, GET/getAssetRenditionTransforms filterable by usage: CMSBRANDWORKZ, WEBEMBED, SITECORE, WORDPRESS, OFFICE, DRUPAL
RightsFixed fields assetStatus (0 hidden, 1 normal, 2 view-only), assetPublishDate, assetExpiryDate via saveMetadata; permission lookups /assets/permissions, /categories/permissionsNo separate rights/licence object documented
Workflow, Web-to-PrintNot in the public collection"Contact Brandworkz" for API services of other modules (Workflow, Web-to-Print) S1
Essentials (5)GET/brands, GET/brands/elements/colours, /fonts, /logos, /styles on main-api.brandworkz.comRead-only brand-kit elements with on-/off-brand status filters S3

Data model

  • Asset: identified by assetGuid (version-independent, recommended), plus a human-friendly sequential serial number (assetSerialNumber / artwork_ID) and assetVersion; assetVersionGuid identifies a specific version. Older endpoints still take serial IDs, "likely to be retired" S1.
  • Shortcut: an alias of an asset in another folder, with its own ID/GUID (many endpoints take assetIDs and shortcutIDs) S1.
  • Category: folder or CMS web page (a folder with a CMS template); search returns both as folders S1. Asset types: Image, Video, Audio, Document, Folder, Webpage, Editable template (W2P), User artwork S1; since v1.7 the type is read from _source.assetType (_type is always _doc) S5.
  • Metadata: metasets referenced by metasetRef (systemRef), fields by systemRef; metadata is not version-specific S1.
  • Search hit: Elasticsearch-style {_id (GUID), _source{title, description, extendedKeywords, thumbnailUrlCdn, objectURL, …}, _score}; sourceFields selects returned fields (all includes document full text — not for production) S1.
  • Response envelope: { "result": {code|status, message}, "data": {…} }; result.status 0 = success S1.

Search & querying

  • GET/simpleSearch?searchterm=… — keyword search, permission-aware, across all asset types by default; filters categoryGUID (descendants), parentCategoryGUID (direct children — used to build a browse UI, sorted folders first then alphabetical), assetType (case-sensitive list), fileType (suffixes), sourceFields; paging from/size (size ≤ 500) S1.
  • POST/search — any valid Elasticsearch query (facets/aggregations possible), executed after the user's permissions are applied; requires knowledge of the index mapping (GET/search/definition) S1.
  • v1.7 change: hits.total became an object {value, relation} instead of an integer S5.
  • Deep pagination limit: Not public (Elasticsearch defaults would cap from + size, but this is not documented Unverified).

Uploads & binaries

Three-step flow, binaries go directly to AWS S3 pre-signed URLs (S3 Transfer Acceleration hosts in the examples) S1:

  1. POST/createUploadPath with fileName, fileSize, categoryGuid, optional uploadType (single-upload | multipart-upload), assetGuid (new version), isCustomThumbnail. Returns assetId, assetVersion, keyName and either one url or an array of urls with uploadId, mainChunkSize, finalChunkSize, chunkNo.
  2. PUT the file (or each chunk, keeping each ETag). Default chunking: files > 15 MB are split into 15 MB parts; chunk size grows if more than 200 parts would be needed. Single PUT theoretical maximum 5 GB; failures likely above 100–200 MB. Upload URLs expire after ~15 minutes (longer for big files). Postman cannot be used for the PUT (extra headers break the S3 signature).
  3. Multipart only: POST/assemble with objectKey, uploadId, parts[{partNumber, eTag}].
  4. POST/importAsset with categoryGuid, keyName, originalFilename, assetId, assetVersion, fileSize; options assetGuid (new version), relativePath (auto-create sub-folders), MD5, duplicateAction (rename | addversion), approved=false + objectWorkflowStageID (enter a workflow), isCustomThumbnail.
  • Response returns technical data (pixels, dpi, colour space, pages, duration, MD5 when de-duplication is on), assetGuid, shortcutCreated/binaryIdenticalToGuid (de-duplication) and nameClash. result.status 1 = error, 2 = not imported (e.g. .exe) S1.
  • Indexing, thumbnails, full-text and colour extraction run asynchronously: ~30 s, up to 2 min for full text and colours; embedded metadata is extracted synchronously, so saveMetadata can be called immediately S1.
  • Downloads: getDownloadOriginalLinks, transform/rendition links (getEmbedLink, getAssetRendition), thumbnails on a CDN (thumbnailUrlCdn, 320×320) S1; Smart Asset Embed links for web delivery S50.

Events & webhooks

  • No public webhook or event subscription API. POST/importAsset lists a webhookId parameter without explanation S1 — purpose Unknown.
  • Change detection: GET/getModifiedResources?modifiedStartDate=…&modifiedEndDate=… returns resources modified or deleted in the window S1.
  • Integration audit trail: GET/integrations/{integrationGuid}/audit S1.

Limits & quirks

  • Do not hard-code api_url, client_id or the version: the vendor retires versions and moves hosts; always call getAPIURL first S1 S5.
  • Two different "client IDs": the site DB id (client_id/client_db/clientDb, from getAPIURL) vs the OAuth consumer ID — and parameter names differ between /oauth/authorize and /oauth/token S1.
  • Many state-changing endpoints are GET requests (e.g. deleteAssets, moveAssets, createCategory, deleteAlbum) S1.
  • Error codes: 401/1 authentication required, 502/2 service not available, 422/3 argument error, 500/4 configuration error; result.status 5 "Service endpoint call failed" with a root cause S1. Choice fields reject unknown options with HTTP 500; duplicate asset titles in a folder return 400 with a suggested name S1.
  • sourceFields=all can return multi-megabyte responses (document full text) S1.
  • Rate limits, quotas and concurrency limits: Not public.
  • Unverified Documentation drift: the public collection (v1.6, 2023) predates the v1.7 changes (2025-01-18) and still documents removed album endpoints and the old _type semantics S1 S5.

SDKs, tools & code samples

Library / toolLanguageMaintainerStatus
bwkz/assetInsert-integration-examplesJavaScript (jQuery; ES6 + Webpack)BrandworkzExamples for embedding the /assetInsert picker; last push 2019-03-28 S6
"Run in Postman" button on the docsPostmanBrandworkzRequires a Postman account; environment variables api_url, client_id, api_version, access_token suggested S1
  • /assetInsert returns a complete HTML/React picker (keyword search, facets, folder browsing, detail view, download options, single/multi-select) to embed in a pop-up or iframe; it calls back the host app with JSON describing the selected files — the vendor's preferred route for CMS/e-commerce "insert asset" integrations S1 S6.
  • No official SDK on npm or PyPI (searched 2026-10-01); no community SDK found (Unknown).

Changelog of the API

DateChange
2025-01-18v1.7 in production (staging from 2024-12-20): hits.total becomes {value, relation}, _type always _doc (use _source.assetType), album IDs UUID4, addAlbumAssets adds permitted transforms, getAlbumAssets returns transforms per asset; removed createAlbumShortLink, getAlbumGlobalTransforms, getAlbumSentEntry; new album/asset download-option endpoints S5
2023-03-29Current public Postman documentation "Brandworkz API (v1.6)" published S1
2022-08-03"Brandworkz Essentials API" documentation published S3
2019-02assetInsert integration examples published on GitHub S6
UndatedgetAssetMetadata deprecated in favour of GET/metadata/asset S1

Stored API specs

2 files · 304 KB · verbatim copies of public vendor filesSpecs README & provenance
FileFormatSizeDownload
brandworkz_postman_api_v1.6.jsonPostman collection290 KBDownload
brandworkz-essentials_postman.jsonPostman collection14 KBDownload
Search the wiki