Search Brand Assets

Search across all brand asset types (images, colors, fonts, videos, audio) in your workspace

Published ·Updated

GET
/v1/brand-assets/search
curl -X GET "https://api.orshot.com/v1/brand-assets/search?query=<QUERY>&types=<TYPES>&page=<PAGE>" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

Overview#

This endpoint allows you to search across all brand asset types in your workspace — images, colors, fonts, videos, and audio — in a single request. You can filter by keyword (matching against names, tags, font families, and color values) and optionally restrict to specific asset types. When no query is provided, it lists all assets of the requested type(s).

Endpoint
https://api.orshot.com/v1/brand-assets/search

Query Parameters#

ParameterTypeRequiredDescription
queryStringNoSearch keyword (case-insensitive). File names, font families, color values and video/audio names match on any part of the text. Tags match only when the whole tag equals the query. Omit to list all assets.
typesStringNoComma-separated asset types to search: image, color, font, video, audio. Defaults to all types if omitted. Unknown types are ignored. If none are valid, the request returns 400.
pageNumberNoPage number for pagination (starts at 1). Defaults to 1.
limitNumberNoNumber of results per type per page (1–50). Defaults to 10.
embedIdStringNoEmbed instance ID. Pair with embedUserId to scope this call to one embed user
embedUserIdStringNoThe same userId your app passes to the embed URL. Requires embedId

Request#

JavaScript
// Omit query to list all assets of the given type
await fetch("https://api.orshot.com/v1/brand-assets/search?types=font", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
JSON
{
  "images": {
    "data": [
      {
        "id": 101,
        "name": "company-logo.png",
        "url": "https://storage.orshot.com/cloud/w-50/renders/brand_assets/company-logopng-R7tL2mWq8Zd.png",
        "tags": ["logo", "brand"],
        "type": "image"
      }
    ],
    "total": 1
  },
  "colors": {
    "data": [
      {
        "id": 5,
        "colorType": "hex",
        "value": "#FF5733",
        "tags": ["primary"],
        "type": "color"
      }
    ],
    "total": 1
  },
  "fonts": {
    "data": [
      {
        "id": 12,
        "name": "Inter",
        "fontFamily": "Inter",
        "url": "https://storage.orshot.com/cloud/w-50/renders/custom_fonts/Inter-Ty6Wb3Nc9Lm.woff2",
        "tags": ["body"],
        "type": "font"
      }
    ],
    "total": 1
  },
  "videos": {
    "data": [
      {
        "id": 8,
        "name": "intro.mp4",
        "url": "https://storage.orshot.com/cloud/w-50/renders/videos/intromp4-Mv2Hc8Ya4Pe.mp4",
        "thumbnailUrl": null,
        "duration": 15,
        "tags": ["intro"],
        "type": "video"
      }
    ],
    "total": 1
  },
  "audios": {
    "data": [
      {
        "id": 42,
        "name": "background-music.mp3",
        "url": "https://storage.orshot.com/cloud/w-50/renders/audio/background-musicmp3-Lp9Xe3Gu6Ra.mp3",
        "duration": 169.5,
        "tags": ["music"],
        "type": "audio"
      }
    ],
    "total": 1
  },
  "page": 1,
  "limit": 10
}

Per-User Libraries#

Pass embedId and embedUserId together to search only that embed user's assets instead of the whole workspace library. This is how one embed serves many brands or tenants, each with its own brand space.

Omit them and this endpoint behaves exactly as documented above. See Per-User Brand Assets for the full picture.

Rate Limits#

  • 30 requests per minute per endpoint

Response Fields#

The response contains only the requested types, ordered by most recently created. Each type includes a data array and a total count for pagination. Top-level page and limit fields reflect the current pagination state. Each url points to the stored file. Treat this URL as opaque.

Images#

FieldTypeDescription
idNumberUnique identifier for the image
nameStringOriginal filename
urlStringDirect URL to the image
tagsString[]Tags associated with the image
typeStringAlways "image"

Colors#

FieldTypeDescription
idNumberUnique identifier for the color
colorTypeStringColor format: hex, rgb, hsl, or gradient
valueStringColor value (e.g. "#FF5733")
tagsString[]Tags associated with the color
typeStringAlways "color"

Fonts#

FieldTypeDescription
idNumberUnique identifier for the font
nameStringDisplay name of the font
fontFamilyStringCSS font-family name
urlStringDirect URL to the font file
tagsString[]Tags associated with the font
typeStringAlways "font"

Videos#

FieldTypeDescription
idNumberUnique identifier for the video
nameStringVideo name
urlStringDirect URL to the video
thumbnailUrlStringPoster image URL. Often null for videos added through the API
durationNumberVideo duration in seconds, or null. Only set when you pass it in metadata on upload
tagsString[]Tags associated with the video
typeStringAlways "video"

Audio#

Returned under the audios key.

FieldTypeDescription
idNumberUnique identifier for the audio
nameStringUploaded file name, or the audio name when there is none
urlStringDirect URL to the audio
durationNumberAudio duration in seconds, or null. Only set when you pass it in metadata on upload
tagsString[]Tags associated with the audio
typeStringAlways "audio"
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required