Skip to main content
Convertly HDAM stores library metadata on each file: tags, description, and optional embedded IPTC/XMP fields on supported images. Metadata powers dashboard search, public faceted search APIs, and CDN delivery identifiers (file id and slug).

​
Metadata fields

FieldStorageLimits
tagsstored_files.metadata.tags (JSON array)Up to 50 tags, 80 characters each
descriptionstored_files.metadata.descriptionUp to 5,000 characters
cdnSlugstored_files.cdn_slug columnUnique per workspace; see URL structure
Update metadata with PATCH /api/files/{id} or the SDK: 
await convertly.storage.files.update(fileId, {
  description: "Golden-hour editorial portrait",
  tags: ["sunset", "editorial", "vertical"],
});
Tags submitted through the API are normalized against your workspace taxonomy when present (synonyms resolve to canonical labels).

​
AI auto-tagging (SDK one-liner)

Generate searchable tags with Forma AI and persist them on the file in one call: 
const result = await convertly.ai.tagFile(fileId, {
  maxTags: 8,
  merge: true,
  locale: "en",
});

console.log(result.tags, result.addedTags, result.summary);
REST equivalent: 
curl -X POST "https://convertly.sh/api/files/{id}/ai-tags" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxTags": 8, "merge": true, "locale": "en" }'
OptionDefaultDescription
maxTags8Maximum tags returned from the model (1–20).
mergetrueMerge with existing tags instead of replacing.
localeenTaxonomy locale used when canonicalizing tags.
prompt—Optional override for the tagging instruction.
Auto-tagging is available for images up to 25 MB and consumes Forma AI quota. Supported image tags are embedded back into the file when the format allows.
POST /api/files/{id}/auto-tags remains available for dashboard compatibility. Prefer /ai-tags for new integrations.
Search the main workspace library with combined text query, tag filters, orientation, mime type, and optional facet counts — for example sunset + vertical + editorial: 
const { files, facets, applied } = await convertly.storage.files.search({
  q: "sunset",
  tags: ["editorial", "vertical"],
  tagMode: "all",
  orientation: "vertical",
  facets: ["tags", "orientation"],
  locale: "en",
  limit: 24,
});
REST: 
curl "https://convertly.sh/api/files/search?q=sunset&tags=editorial,vertical&tagMode=all&orientation=vertical&facets=tags,orientation&locale=en" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
Query paramDescription
qFree-text search across filename, slug, description, and tags.
tagsComma-separated tag list.
tagModeany (default) or all — require every tag vs match any.
orientationvertical, horizontal, or square (derived from width/height).
folderIdRestrict to a folder; use null for root only.
mimePrefixe.g. image/ or video/mp4.
facetsComma-separated: tags, orientation, mimeType.
localeTaxonomy locale for synonym resolution and facet labels.
Faceted search applies to the main workspace library (not WordPress isolated buckets). Isolated site tokens should use GET /api/files with q for scoped listing.

​
Taxonomy, synonyms, and locales

Define a controlled vocabulary per workspace and locale. Synonyms map contributor input ("portrait") to canonical slugs (portrait-orientation) used in search filters. 
const { terms } = await convertly.library.taxonomy.list({ locale: "en" });

await convertly.library.taxonomy.create({
  slug: "editorial",
  label: "Editorial",
  groupName: "Style",
  synonyms: ["magazine", "editorial-style"],
  locale: "en",
});
MethodEndpoint
GET/api/library/taxonomy/terms?locale=en
POST/api/library/taxonomy/terms
PATCH/api/library/taxonomy/terms/{id}
DELETE/api/library/taxonomy/terms/{id}
Each term is scoped to a workspace and locale. Duplicate slugs per locale return 409. AI auto-tagging and manual tag updates canonicalize against the active locale taxonomy when available.

​
Contributor tag UI (dashboard)

Contributors do not need a separate tagging product — the dashboard already exposes metadata editing in the Assets lightbox:
  1. Open any file in Assets and expand the info sidebar.
  2. Edit Tags inline (type and press Enter, or remove with the chip control).
  3. Use Auto tags on images to run the same AI pipeline as convertly.ai.tagFile, then review and save.
The lightbox uses the same PATCH /api/files/{id} metadata path as the API. Taxonomy canonicalization applies on save when terms exist for the workspace locale. For stock or contributor portals you build on top of Convertly, wire your UI to:
  • convertly.storage.files.update(id, { tags }) for manual tagging
  • convertly.ai.tagFile(id) for AI suggestions
  • convertly.storage.files.search({ tags, tagMode: "all" }) for public browse pages

Files and storage

Uploads, folders, CDN slugs, and storage limits.

JavaScript SDK

convertly.ai, convertly.storage.files.search, and taxonomy helpers.