DAM Assets API ============== .. contents:: :depth: 2 The DAM (Digital Asset Manager) assets API allows you to manage digital assets for your site, including images and files. Base path: ``/api/1.3/dam/assets`` Authentication is required on all endpoints via ``?api_key=`` query parameter or ``Authorization`` header. .. _listing-dam-assets: Listing assets -------------- Returns a paginated list of assets for the site. .. code:: GET /api/1.3/dam/assets Parameters ********** +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | Name | Type | Default | Description | +=========================+==========+==================+====================================================================================================+ | ``type`` | String | || Filter by asset type. | | | | || Choices: ``all``, ``admin``, ``community``. | | | | || Non-admin API keys default to ``admin`` when omitted. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``file_type`` | String | ``all`` || Filter by file type. | | | | || Choices: ``image``, ``file``, ``all``. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``in_trash`` | Integer | || Filter by trash status. | | | | || Choices: ``0``, ``1``. | | | | || Ignored for non-admin keys (always ``false``). | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``tags`` | String | | Comma-separated list of tags to filter by. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``user_id`` | Integer | | Filter by creator user ID. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``date_added`` | String | | Filter assets created on this date. ISO 8601 format (e.g. ``2024-01-15``). | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``search`` | String | | Full-text search across title, alt text, credit, source info, and filename. Minimum 3 characters. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``file_id`` | Integer | | Filter by file ID. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``offset`` | Integer | ``0`` | Pagination offset. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``count`` | Integer | ``100`` | Number of results to return. Max ``100``. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``sort_by`` | String | ``created_ts`` || Sort field. | | | | || Choices: ``created_ts``, ``score``. | | | | || ``score`` only applies when ``search`` is provided. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``order`` | String | ``desc`` || Sort order. | | | | || Choices: ``asc``, ``desc``. | | | | || Ignored when ``sort_by=score``. | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ | ``thumbnail_sizes`` | String | | Comma-separated list of thumbnail sizes to include for image assets (e.g. ``300,600``). | +-------------------------+----------+------------------+----------------------------------------------------------------------------------------------------+ Response ******** .. code:: json { "total": 42, "items": [, ...] } See :ref:`dam-asset-object` for the asset object structure. .. _getting-dam-asset: Getting an asset ---------------- Returns a single asset by ID. .. code:: GET /api/1.3/dam/assets/ Parameters ********** +---------------------+--------+---------------------------------------------------+ | Name | Type | Description | +=====================+========+===================================================+ | ``thumbnail_sizes`` | String | Comma-separated thumbnail sizes for image assets. | +---------------------+--------+---------------------------------------------------+ Response ******** The response payload is an asset object. See :ref:`dam-asset-object`. .. note:: Non-admin API keys can retrieve assets of any type, but trashed assets are not accessible. .. _creating-dam-asset: Creating an asset ----------------- Creates a new asset. Requires ``publish_post`` or ``manage_design`` permission on the site. .. code:: POST /api/1.3/dam/assets Parameters ********** +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | Name | Type | Required | Description | +========================+==================+==========+=============================================================================+ | ``file_type`` | Integer | Yes || File type. | | | | || Choices: ``0`` (image), ``1`` (file). | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``file_id`` | Integer | Yes | ID of the existing image or file object. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``image_title`` | String | No | Asset title. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``filename`` | String | No | Original filename. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``alt_text`` | String | No | Accessibility alt text. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``credit`` | String | No | Photo/media credit. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``source_info`` | String | No | Source information. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``tags`` | Array of strings | No || Tags. | | | | || Tags prefixed with ``*`` are admin-only and stripped for non-admin users. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ | ``site_specific_data`` | Object | No | Arbitrary site-specific metadata. | +------------------------+------------------+----------+-----------------------------------------------------------------------------+ Response ******** Returns the created asset object. See :ref:`dam-asset-object`. Returns ``400`` if the asset already exists (duplicate ``file_type`` + ``file_id``). .. _updating-dam-asset: Updating an asset ----------------- Updates an existing asset. Requires ``publish_post`` or ``manage_design`` permission. ``file_type`` and ``file_id`` are ignored if provided. .. code:: PUT /api/1.3/dam/assets/ Parameters ********** +------------------------+------------------+--------------------------------+ | Name | Type | Description | +========================+==================+================================+ | ``image_title`` | String | Asset title. | +------------------------+------------------+--------------------------------+ | ``filename`` | String | Filename. | +------------------------+------------------+--------------------------------+ | ``alt_text`` | String | Alt text. | +------------------------+------------------+--------------------------------+ | ``credit`` | String | Credit. | +------------------------+------------------+--------------------------------+ | ``source_info`` | String | Source info. | +------------------------+------------------+--------------------------------+ | ``tags`` | Array of strings | Tags. | +------------------------+------------------+--------------------------------+ | ``in_trash`` | Boolean | Move to / restore from trash. | +------------------------+------------------+--------------------------------+ | ``site_specific_data`` | Object | Site-specific metadata. | +------------------------+------------------+--------------------------------+ Response ******** The same specification from :ref:`creating-dam-asset` section applies here. .. _bulk-dam-assets: Bulk operations --------------- Performs the same operation on multiple assets in a single request. .. code:: POST /api/1.3/dam/assets?bulk=1 PUT /api/1.3/dam/assets?bulk=1 DELETE /api/1.3/dam/assets?bulk=1 Set the ``X-Http-Method-Override: PUT|POST|DELETE`` header to specify the method when using ``POST``. Request body ************ Array of operation objects: .. code:: json [ {"file_id": 123, "data": {"image_title": "New title"}}, {"file_id": 456, "data": {"in_trash": true}} ] Response ******** Map of ``file_id`` → result: .. code:: json { "123": {"status_code": 200, "data": {...}}, "456": {"status_code": 200, "data": {...}} } .. _dam-asset-object: Asset object ------------ +------------------------+------------------+----------------------------------------------------------------------+ | Field | Type | Description | +========================+==================+======================================================================+ | ``id`` | Integer | Asset ID. | +------------------------+------------------+----------------------------------------------------------------------+ | ``roar_id`` | Integer | Site ID. | +------------------------+------------------+----------------------------------------------------------------------+ | ``user_id`` | Integer | Creator user ID. | +------------------------+------------------+----------------------------------------------------------------------+ | ``file_type`` | Integer || File type. | | | || Choices: ``0`` (image), ``1`` (file). | +------------------------+------------------+----------------------------------------------------------------------+ | ``file_type_name`` | String || File type name. | | | || Choices: ``"image"``, ``"file"``. | +------------------------+------------------+----------------------------------------------------------------------+ | ``file_id`` | Integer | ID of the underlying image or file. | +------------------------+------------------+----------------------------------------------------------------------+ | ``in_trash`` | Boolean | Whether the asset is in trash. | +------------------------+------------------+----------------------------------------------------------------------+ | ``image_title`` | String or null | Asset title. | +------------------------+------------------+----------------------------------------------------------------------+ | ``filename`` | String or null | Original filename. | +------------------------+------------------+----------------------------------------------------------------------+ | ``alt_text`` | String or null | Alt text. | +------------------------+------------------+----------------------------------------------------------------------+ | ``credit`` | String or null | Credit. | +------------------------+------------------+----------------------------------------------------------------------+ | ``source_info`` | String or null | Source info. | +------------------------+------------------+----------------------------------------------------------------------+ | ``tags`` | Array of strings || Tags. | | | || Admin-only tags (prefixed ``*``) are hidden for non-admin keys. | +------------------------+------------------+----------------------------------------------------------------------+ | ``site_specific_data`` | Object or null | Site-specific metadata. | +------------------------+------------------+----------------------------------------------------------------------+ | ``created_ts`` | Float | Creation timestamp (Unix seconds). | +------------------------+------------------+----------------------------------------------------------------------+ | ``updated_ts`` | Float | Last update timestamp (Unix seconds). | +------------------------+------------------+----------------------------------------------------------------------+ | ``user_site_title`` | String | Author profile site title (if available). | +------------------------+------------------+----------------------------------------------------------------------+ | ``user_site_uri`` | String | Author profile site URI (if available). | +------------------------+------------------+----------------------------------------------------------------------+ | ``thumbnails`` | Object | (Images only) Map of size → URL for requested ``thumbnail_sizes``. | +------------------------+------------------+----------------------------------------------------------------------+ | ``image_size`` | String | (Images only) Dimensions as ``"WIDTHxHEIGHT"``. | +------------------------+------------------+----------------------------------------------------------------------+ | ``shortcode`` | String | Shortcode string to embed this asset. | +------------------------+------------------+----------------------------------------------------------------------+ | ``media_html`` | String | Rendered HTML for the asset. | +------------------------+------------------+----------------------------------------------------------------------+ | ``shortcode_id`` | String | Unique shortcode identifier. | +------------------------+------------------+----------------------------------------------------------------------+ | ``shortcode_params`` | Object || Shortcode parameters. | | | || Includes ``dam=1``, ``expand=1``, alt text, and filename. | +------------------------+------------------+----------------------------------------------------------------------+