Developer Guide

Auth

Generate API keys from DDAM Admin. Manual upload in the DDAM UI does not require an API key, but all API integrations do.

Base URL

http://127.0.0.1:8020

Auth header

X-API-Key: YOUR_DDAM_API_KEY

App Settings Contract

DDAM_ENABLED=true
DDAM_BASE_URL=https://ddam.example.com
DDAM_API_KEY=generated-in-ddam-admin
DDAM_TIMEOUT_SECONDS=30

Consumer Pattern

• List or search assets from `GET /api/v1/assets` with controlled filters.
• Use returned URL fields by strict contract: preview_url must stay preview-safe binary media, inline_url must stay direct embeddable raw media, download_url must stay binary download media, and public_page_url is the only human-facing page URL.
• Consumer apps should not need HTML fallback logic or content sniffing for asset URL fields returned by the API.
• Load controlled combos like product lists from DDAM public option endpoints instead of mirroring taxonomy locally.
• Consumers should degrade safely if DDAM is disabled or unhealthy.

import requests

response = requests.get(
    "http://127.0.0.1:8020/api/v1/assets",
    headers={"X-API-Key": "YOUR_DDAM_API_KEY"},
    params={
        "product": "genialcloud-proj",
        "asset_type": "image",
        "language": "english",
        "status": "ready",
    },
    timeout=30,
)
response.raise_for_status()
items = response.json()["items"]

Producer Pattern

• Publish only durable, reusable outputs into DDAM.
• Send source app, optional workflow, and metadata that preserves lineage.
• Use `external_key` when you need idempotent publishing from a producer app.

curl -X POST "http://127.0.0.1:8020/api/v1/assets" \
  -H "X-API-Key: YOUR_DDAM_API_KEY" \
  -F "file=@/path/to/asset.png" \
  -F "asset_type=image" \
  -F "product=avantune-generic" \
  -F "source_app=developer_daily" \
  -F "language=english" \
  -F "status=ready" \
  -F "title=Video Daily Screenshot 1" \
  -F 'metadata_json={"workflow":"video","job_id":"...","job_output_kind":"selected_screenshot"}' \
  -F 'tags=["manualstudio","video","selected_screenshot"]' \
  -F "is_public=false"

Endpoint Catalog

GET /health

Health check for service reachability.

GET /api/public/options/products

Public taxonomy endpoint for product combo values. No API key required.

GET /api/public/options/languages

Public producer-language endpoint for publish selectors. No API key required.

GET /api/v1/assets

List assets with filter and pagination support.

POST /api/v1/assets

Upload and register a new reusable asset.

GET /api/v1/assets/{asset_id}

Fetch one asset record and resolved labels.

GET /api/v1/assets/{asset_id}/download

Download the stored asset payload.

GET /public/assets/{asset_id}

Human-facing public asset page route. This compatibility flow may render or redirect to an HTML page and should not be used by downstream renderers as a raw media URL.

GET /public/assets/{asset_id}/binary

Public raw media route. This endpoint is intended for direct asset bytes, not an HTML landing page.

Returned internal media URLs

preview_url, inline_url, and download_url are returned as absolute DDAM URLs for sibling apps. inline_url and public_url must resolve to direct binary-safe media responses, never a page shell or HTML landing flow. public_page_url is the separate human-facing public asset page.

GET /api/v1/assets/{asset_id}/relationships

Read parent or child lineage relationships for an asset.

Filter Contract

curl "http://127.0.0.1:8020/api/v1/assets?product=genialcloud-proj&asset_type=image&language=english&status=ready&page=1&page_size=15" \
  -H "X-API-Key: YOUR_DDAM_API_KEY"

{
  "product": "genialcloud-proj",
  "asset_type": "image",
  "language": "english",
  "status": "ready",
  "page": 1,
  "page_size": 15
}

Sample Asset Response

{
  "id": "3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10",
  "asset_type": "image",
  "product": "avantune-generic",
  "source_app": "developer_daily",
  "title": "Video Daily Screenshot 1",
  "language": "english",
  "status": "ready",
  "is_public": true,
  "public_url": "https://media.avantune.com/ddam/public/assets/avantune-generic/image/3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10/screenshot-1.png",
  "public_page_url": "https://media.avantune.com/ddam/public/pages/3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10/index.html",
  "preview_url": "http://127.0.0.1:8020/ui/assets/3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10/preview?v=1775587000",
  "inline_url": "http://127.0.0.1:8020/ui/assets/3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10/inline?v=1775587000",
  "download_url": "http://127.0.0.1:8020/api/v1/assets/3f2fd8cb-59d3-4f58-9ae4-a4f2b0c8ab10/download"
}

Public Option API

Use this public endpoint for app combos that must stay aligned with DDAM controlled vocabulary across different servers.

curl "http://127.0.0.1:8020/api/public/options/products"

curl "http://127.0.0.1:8020/api/public/options/languages"

Sample Product Options Response

{
  "items": [

    { "value": "avantune", "label": "Avantune" },

    { "value": "avantune-generic", "label": "Genialcloud" }

  ],
  "total": 11
}

{
  "items": [
    { "value": "both", "label": "Both" },
    { "value": "english", "label": "English" },
    { "value": "italian", "label": "Italian" }
  ]
}

Sample Create Payload

{
  "asset_type": "image",
  "product": "avantune-generic",
  "source_app": "developer_daily",
  "language": "english",
  "status": "ready",
  "title": "Video Daily Screenshot 1",
  "description": "Selected screenshot published from DeveloperDaily.",
  "metadata_json": {
    "workflow": "video",
    "job_id": "...",
    "job_output_kind": "selected_screenshot"
  },
  "tags": [
    "developerdaily",
    "video",
    "selected_screenshot"
  ],
  "is_public": false
}

Producer apps may populate publish-language selectors from GET /api/public/options/languages. Asset uploads to POST /api/v1/assets may include a language field. Recommended producer values are both, english, and italian.

Asset uploads to POST /api/v1/assets may include a status field. Current supported DDAM values are ready, draft, and archived.

metadata_json and tags are sent as JSON strings inside multipart form data.

Controlled Vocabulary