Digital Backdrops API: Catalogue and Partner Integration

Overview

The API serves the same catalogue as this website: 102 published scenes today, each with landscape, square and portrait variants. Responses are JSON. Catalogue responses include public, watermarked preview images (up to 1280px) and the real pixel sizes of the high-resolution files, never the files themselves.

Public catalogue: no key, CORS open, cached. Good for showing backdrops in your app.
Partner access: a key raises the rate limits and, with the right scope, can request short-lived links to high-resolution files for your own eligible users.
Website endpoints (accounts, checkout, free downloads, contact) are same-origin only and are listed for completeness.

The library is a general-purpose partner API, not built for one partner. TemplatesBooth, run by the same company, is planned as the first integration; it is not live yet.

Authentication

Catalogue endpoints work without a key. Partners send their key as a bearer token:

Authorization: Bearer dbk_live_…

Server-side only. Never put a key in a browser, a mobile app bundle or a public repository. We store only a hash of each key.
Scopes. catalog:read for the catalogue at partner rate limits; downloads:hd to request high-resolution links.
Unknown or revoked keys get 401 invalid_api_key; a missing scope gets 403 insufficient_scope.

A key is not a licence to redistribute

Partners use the files under a separate agreement, and the licence still applies to every end user. The API never exposes private storage paths or permanent file URLs.

Rate limits and caching

Public catalogue: 60 requests per minute per IP address.
With a partner key: 600 requests per minute per key, or the rate agreed for your key.
Over the limit you get 429 rate_limited with a Retry-After header in seconds.
Catalogue responses carry an ETag. Send it back as If-None-Match and you get a 304 with no body when nothing changed. Each response includes catalogue_revision, which changes whenever the catalogue does.
Authenticated responses are sent with Cache-Control: private, no-store.

Errors

Every error has the same shape and the right HTTP status:

{
  "error": {
    "code": "not_found",
    "message": "No published collection with this id.",
    "request_id": "8c1f2a7e4b9d0f11-LHR",
    "field": "collection"
  }
}

Quote the request_id when you contact us about a failed call.

Catalogue endpoints

List published collections

curl https://digital-backdrops.com/api/v1/catalog/collections

Only collections with at least 6 published scenes are returned. external_refs maps each collection to partner collection slugs. Response (first item shown, from today's catalogue):

{
  "data": [
    {
      "id": "christmas",
      "name": "Christmas",
      "url": "https://digital-backdrops.com/christmas-digital-backdrops/",
      "parent": null,
      "group": "seasonal",
      "scene_count": 26,
      "external_refs": {
        "templatesbooth": "christmas"
      }
    }
  ],
  "total": 14,
  "scene_total": 102,
  "min_scenes_to_publish": 6,
  "catalogue_revision": "9b9f82ad7620c944"
}

List backdrops

curl "https://digital-backdrops.com/api/v1/catalog/backdrops?collection=christmas&orientation=landscape&limit=24"

Filters: collection, external (for example templatesbooth:christmas), q (words), orientation, color, style, capacity (1-3, 4-6, 7+), pose, setting and light (direction or temperature). Pages hold 24 items by default, up to 100. Follow next_cursor until it is null.

Response for ?limit=1 (each item also has variants, left out here; see the next example):

{
  "data": [
    {
      "id": "db-0001",
      "slug": "peach-balloon-arch-play-tent",
      "title": "Peach Balloon Arch with Play Tent",
      "description": "A full peach, ivory and champagne balloon arch against a warm plaster studio wall, dressed with blush roses and baby's breath. A small canvas play tent and floor cushions sit beside it, and window light falls across the wall from the left. It suits children's birthdays, baby showers and boho party portraits.",
      "alt": "Empty studio backdrop with a peach, ivory and champagne balloon arch, blush roses, a small cream play tent and cushions on a pale oak floor",
      "use_notes": "Place the subject under the arch. There is room for one to three people standing, or a child seated on the floor in front. Light comes from the left, so light your subject from the same side.",
      "page_url": "https://digital-backdrops.com/backdrops/peach-balloon-arch-play-tent/",
      "primary_collection": "birthday-balloons",
      "collections": [
        "birthday-balloons",
        "birthday",
        "baby-shower"
      ],
      "feature": "balloon arch",
      "setting": "studio",
      "styles": [
        "balloon",
        "floral",
        "boho"
      ],
      "colors": [
        "peach",
        "ivory",
        "champagne",
        "blush"
      ],
      "capacity": "1-3",
      "pose": [
        "standing",
        "seated"
      ],
      "camera": "eye-level",
      "light_direction": "left",
      "light_temp": "warm",
      "tags": [
        "peach balloon arch backdrop",
        "boho birthday backdrop",
        "balloon arch digital background"
      ],
      "native": {
        "width": 2880,
        "height": 2880
      },
      "upscaled": false,
      "ai_generated": true,
      "og_image": {
        "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-og.jpg",
        "width": 1200,
        "height": 630
      },
      "licence_url": "https://digital-backdrops.com/licensing/",
      "status": "published",
      "published_at": "2026-11-12T00:00:00Z",
      "updated_at": "2026-11-12T00:00:00Z"
    }
  ],
  "total": 102,
  "limit": 1,
  "next_cursor": "YTpkYi0wMDAx",
  "filters": {},
  "catalogue_revision": "9b9f82ad7620c944"
}

One backdrop

curl https://digital-backdrops.com/api/v1/catalog/backdrops/db-0001

Accepts the asset id or the slug. variants lists each shape with its high-resolution size, the public preview and its srcset. upscaled is false for every scene. Full response for today's first scene:

{
  "data": {
    "id": "db-0001",
    "slug": "peach-balloon-arch-play-tent",
    "title": "Peach Balloon Arch with Play Tent",
    "description": "A full peach, ivory and champagne balloon arch against a warm plaster studio wall, dressed with blush roses and baby's breath. A small canvas play tent and floor cushions sit beside it, and window light falls across the wall from the left. It suits children's birthdays, baby showers and boho party portraits.",
    "alt": "Empty studio backdrop with a peach, ivory and champagne balloon arch, blush roses, a small cream play tent and cushions on a pale oak floor",
    "use_notes": "Place the subject under the arch. There is room for one to three people standing, or a child seated on the floor in front. Light comes from the left, so light your subject from the same side.",
    "page_url": "https://digital-backdrops.com/backdrops/peach-balloon-arch-play-tent/",
    "primary_collection": "birthday-balloons",
    "collections": [
      "birthday-balloons",
      "birthday",
      "baby-shower"
    ],
    "feature": "balloon arch",
    "setting": "studio",
    "styles": [
      "balloon",
      "floral",
      "boho"
    ],
    "colors": [
      "peach",
      "ivory",
      "champagne",
      "blush"
    ],
    "capacity": "1-3",
    "pose": [
      "standing",
      "seated"
    ],
    "camera": "eye-level",
    "light_direction": "left",
    "light_temp": "warm",
    "tags": [
      "peach balloon arch backdrop",
      "boho birthday backdrop",
      "balloon arch digital background"
    ],
    "native": {
      "width": 2880,
      "height": 2880
    },
    "upscaled": false,
    "ai_generated": true,
    "variants": {
      "landscape": {
        "id": "landscape",
        "aspect": "3:2",
        "hd": {
          "width": 2880,
          "height": 1920,
          "bytes": 1428789,
          "format": "jpeg",
          "native": true
        },
        "preview": {
          "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-landscape-1280.jpg",
          "width": 1280,
          "height": 853,
          "bytes": 132771,
          "watermarked": true,
          "srcset": [
            {
              "width": 400,
              "height": 267,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-landscape-400.webp"
            },
            {
              "width": 640,
              "height": 427,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-landscape-640.webp"
            },
            {
              "width": 960,
              "height": 640,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-landscape-960.webp"
            },
            {
              "width": 1280,
              "height": 853,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-landscape-1280.webp"
            }
          ]
        },
        "free_download": {
          "width": 1280,
          "height": 853,
          "bytes": 132771,
          "format": "jpeg",
          "watermarked": true
        }
      },
      "square": {
        "id": "square",
        "aspect": "1:1",
        "hd": {
          "width": 2880,
          "height": 2880,
          "bytes": 1971171,
          "format": "jpeg",
          "native": true
        },
        "preview": {
          "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-square-1280.jpg",
          "width": 1280,
          "height": 1280,
          "bytes": 182193,
          "watermarked": true,
          "srcset": [
            {
              "width": 400,
              "height": 400,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-square-400.webp"
            },
            {
              "width": 640,
              "height": 640,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-square-640.webp"
            },
            {
              "width": 960,
              "height": 960,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-square-960.webp"
            },
            {
              "width": 1280,
              "height": 1280,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-square-1280.webp"
            }
          ]
        },
        "free_download": {
          "width": 1280,
          "height": 1280,
          "bytes": 182193,
          "format": "jpeg",
          "watermarked": true
        }
      },
      "portrait": {
        "id": "portrait",
        "aspect": "2:3",
        "hd": {
          "width": 1920,
          "height": 2880,
          "bytes": 1406723,
          "format": "jpeg",
          "native": true
        },
        "preview": {
          "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-portrait-1280.jpg",
          "width": 853,
          "height": 1280,
          "bytes": 133989,
          "watermarked": true,
          "srcset": [
            {
              "width": 267,
              "height": 400,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-portrait-400.webp"
            },
            {
              "width": 427,
              "height": 640,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-portrait-640.webp"
            },
            {
              "width": 640,
              "height": 960,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-portrait-960.webp"
            },
            {
              "width": 853,
              "height": 1280,
              "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-portrait-1280.webp"
            }
          ]
        },
        "free_download": {
          "width": 853,
          "height": 1280,
          "bytes": 133989,
          "format": "jpeg",
          "watermarked": true
        }
      }
    },
    "og_image": {
      "url": "https://digital-backdrops.com/images/backdrops/peach-balloon-arch-play-tent-digital-backdrop-og.jpg",
      "width": 1200,
      "height": 630
    },
    "licence_url": "https://digital-backdrops.com/licensing/",
    "status": "published",
    "published_at": "2026-11-12T00:00:00Z",
    "updated_at": "2026-11-12T00:00:00Z"
  },
  "catalogue_revision": "9b9f82ad7620c944"
}

Changes since your last sync

curl "https://digital-backdrops.com/api/v1/catalog/changes?since=2026-11-12T00:00:00Z"

Returns scenes published, updated or retired after since, oldest first, up to 500 per call. Store next_cursor and pass it as since next time. Remove retired scenes from your app.

Quick start: show matching backdrops by external ref

A template site that already has its own collections, such as TemplatesBooth, can show matching backdrops without storing our ids. All calls are made from your server.

Find which of our collections map to your slug:

curl "https://digital-backdrops.com/api/v1/catalog/collections?external=templatesbooth:christmas" \
  -H "Authorization: Bearer $DBK_KEY"

List the backdrops for that slug, following next_cursor:

curl "https://digital-backdrops.com/api/v1/catalog/backdrops?external=templatesbooth:christmas&limit=100" \
  -H "Authorization: Bearer $DBK_KEY"

Show the preview.url images (watermarked) and link to page_url. Keep catalogue_revision and poll

curl "https://digital-backdrops.com/api/v1/catalog/changes?since=$NEXT_CURSOR" -H "Authorization: Bearer $DBK_KEY"

to stay in sync.

When one of your eligible members needs the clean file, request a link (see below) and redirect them to it.

HD delivery

With scope downloads:hd, your server can request a link to a high-resolution file:

curl -X POST https://digital-backdrops.com/api/v1/downloads \
  -H "Authorization: Bearer $DBK_KEY" -H "Content-Type: application/json" \
  -d '{ "asset_id": "db-0001", "variant": "landscape", "end_user_ref": "member-48213" }'

The response holds a url that works for 120 seconds, plus the file name, byte size, checksum and pixel size.
Redirect your user to the URL straight away; do not store it or show it publicly.
end_user_ref is an optional reference of your own for your audit (letters, digits and _.:-, up to 64 characters). Never send an email address.
You decide which of your users are eligible, and every call is logged against your key. GET /partner/usage shows your recent usage.

All endpoints

Catalogue and partner endpoints:

Endpoint	What it does	Auth
`GET /catalog/collections`	Published collections	None, or partner key
`GET /catalog/backdrops`	List backdrops	None, or partner key
`GET /catalog/backdrops/{id}`	One backdrop	None, or partner key
`GET /catalog/changes`	Changes since a point (partner sync)	None, or partner key
`POST /downloads`	Authorise an HD download	Session or partner key
`GET /files/{token}`	Download the HD file (attachment)	Same-origin (website)
`GET /partner/usage`	The calling key's usage	Partner key

Website endpoints (same-origin, used by this site's own pages):

Endpoint	What it does	Auth
`POST /free-download-intents`	Start a free download	Same-origin (website)
`POST /free-download-intents/{id}/complete`	Get the free file link	Same-origin (website)
`GET /free-files/{token}`	Download the free file (attachment)	Same-origin (website)
`POST /waitlist`	Join the lifetime-access waitlist	Same-origin (website)
`POST /contact`	Contact form	Same-origin (website)
`POST /auth/signup`	Create an account	Same-origin (website)
`POST /auth/login`	Log in	Same-origin (website)
`POST /auth/logout`	Log out	Same-origin (website)
`POST /auth/reset-request`	Ask for a password reset link	Same-origin (website)
`POST /auth/reset`	Set a new password from a reset link	Same-origin (website)
`GET /me`	Current user	Optional session
`GET /me/entitlements`	Effective entitlement	Session cookie
`POST /checkout/sessions`	Start checkout (USD 27, once)	Session cookie
`POST /stripe/webhook`	Stripe webhook (Stripe only)	Same-origin (website)

Paths are relative to https://digital-backdrops.com/api/v1. The full schema, with every field and error code, is in the OpenAPI document.

Getting a partner key

Keys are issued by hand, case by case. Use the contact form, choose "API and partners", and tell us about your product, how you plan to show the backdrops, and whether you need high-resolution delivery. We will reply with the terms and a key. Using the public catalogue needs no key and no agreement beyond the terms of use.