User Guide: DAM Asset Search API

1. Document Purpose

This guide provides business, functional and technical context to help API consumers understand and integrate the API. It complements the OpenAPI specification (specs/openapi.yaml) and is part of the mandatory documentation set for each version (Major.Minor.Patch).

2. Target Audience

Profile	Role
Product Owner	Understand the business scope and value of the API
Developer	Implement and integrate the API
QA / Architect	Validate expected behaviors and technical compliance
Customer Connect API (CCA)	Support API consumers during onboarding and integration

3. API Overview

3.1 Business Context

The API retrieves assets stored in the Accor Digital Asset Management (DAM) whose metadata matches the query parameters. It lets front-end applications and partners find the right visual or document content (for example, images of a given brand, with alt texts in a given language) without browsing the DAM directly.

3.2 Main Features

• Search assets by brand.
• Filter on any asset metadata property (alt texts, captions, title, description, geolocation, rights, author, creation date, etc.).
• Keep only assets that have a Master Dynamic Media URL (isDmUrlPresent).
• Sort results (orderby, sort).
• Paginate results (limit, offset) and follow the pagination.next link.

3.3 Known Limitations

• Read-only: only GET is supported (any other method returns 405).
• All query parameters are optional. Unknown query parameters are rejected with 400.
• Metadata filters are query parameters named after the DAM property in camelCase (for example the DAM property ace:altTextEN is aceAltTextEN, and jcr:uuid is jcrUuid).
• Sorting is only available on aceCreationDate and jcrLastModified.

4. Access & Security

4.1 Access Requirements

Requirement	Provided by Accor	Consumer Action Required
Client ID / API Key	✅	🔲 Request via onboarding

4.2 Authentication & Headers

• Auth method: API Key
• Required header: apikey

4.3 Environments

Environment	Base URL
Testing	https://rec-api.accor.com
Preproduction	https://pre-api.accor.com
Production	https://api.accor.com

5. API Behavior

5.1 Traceability & Telemetry

Every call is traced by the API gateway. When contacting support, provide the date and time of the call, the request URL (without the API key) and the HTTP status code received.

5.2 Health Check

No dedicated health endpoint is exposed. A GET /ecom/v1/assets?limit=1 call returning 200 confirms that the API and your API key are working.

6. Endpoints

GET /ecom/v1/assets

Description: Returns the assets of the DAM whose metadata matches the query parameters.

Request rules: all parameters are optional.

Parameter	Description
brand	Target brand code (for example twf, ibh, sof). See the OpenAPI specification for the full list.
limit	Maximum number of assets to return
offset	Number of assets to skip
orderby	Property to sort by: aceCreationDate or jcrLastModified
sort	Sort order: asc or desc
isDmUrlPresent	true to return only assets with a Master Dynamic Media URL
ace… / jcrUuid	Metadata filters, for example aceAltTextEN, aceTitle, aceGeoCountry, aceAssetId, jcrUuid

Response behavior

• 200: returns an assets array and a pagination object.
• 404: no asset matches the query.

Pagination object

Field	Description
total	Total number of assets matching the query
offset	Offset of the current page
limit	Maximum number of assets in the current page
hasMore	true if more assets are available
next	URL of the next page (present when hasMore is true)

7. Usage Examples

🔍 Search assets of a brand, newest first

curl -G "https://api.accor.com/ecom/v1/assets" \
  -H "apikey: <YOUR_API_KEY>" \
  --data-urlencode "brand=twf" \
  --data-urlencode "orderby=aceCreationDate" \
  --data-urlencode "sort=desc" \
  --data-urlencode "limit=1"

Response (abridged):

{
  "assets": [
    {
      "assetId": "5304-56",
      "altTextEn": "Alternative text in English",
      "altTextFr": "Texte alternatif en français",
      "authorCompany": "Photographer's Studio Inc.",
      "businessDomain": "hospitality"
    }
  ],
  "pagination": {
    "total": 120,
    "offset": 0,
    "limit": 1,
    "hasMore": true,
    "next": "/ecom/v1/assets?brand=twf&orderby=aceCreationDate&sort=desc&limit=1&offset=1"
  }
}

🔍 Filter on a metadata property

curl -G "https://api.accor.com/ecom/v1/assets" \
  -H "apikey: <YOUR_API_KEY>" \
  --data-urlencode "brand=sof" \
  --data-urlencode "aceGeoCountry=France" \
  --data-urlencode "isDmUrlPresent=true"

🔍 Retrieve all pages

1. Call GET /ecom/v1/assets with the desired limit.
2. While pagination.hasMore is true, call the URL given in pagination.next (with the same apikey header).
3. Stop when hasMore is false.

8. Error Codes

Error responses are JSON objects with the fields title, status and code.

HTTP Code	Error	Description	Recommended Action
400	Bad Request	Invalid or unknown query parameter	Check parameter names and values against the specification
401	Unauthorized	Missing or invalid API key	Check the apikey header
403	Forbidden	API key not allowed to consume this API	Contact support to request access
404	Not Found	No matching asset in the DAM	Relax the filters
405	Not Allowed	Method other than GET	Use GET
500	Internal Server Error	Unexpected backend issue	Retry later or escalate to support