---
name: asset-search-api
description: >-
  HTTP API for searching stock assets (images, video, audio, icons, 3D) across multiple
  providers with one normalized JSON response. Use when calling anyasset.dev or integrating
  client apps that fetch metadata and outbound URLs (not file hosting).
---

# AnyAsset Search API — consumption

**Base URL (production):** `https://anyasset.dev`

All responses are **JSON** unless noted. No API key is required **to call** the public service; individual providers in results may still require attribution or license checks in your product.

---

## `GET /search`

Unified search. Returns `{ "query", "results", "errors", "meta" }`.

### Query parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `q` | yes | Search string (1–500 chars). |
| `type` | no | `image` · `vector` · `icon` · `video` · `audio` · `model3d` · `any` (default: any). |
| `sources` | no | Comma-separated provider ids. Omit to query all providers the deployment supports. |
| `limit` | no | Per-provider hint, default 20, max 100. |
| `page` | no | Page hint, default 1, max 1000. |

### Example

```
GET https://anyasset.dev/search?q=tree&type=image&sources=openverse&limit=10
```

### Response: `meta`

| Field | Type | Meaning |
|-------|------|---------|
| `cached` | boolean | Response served from cache. |
| `durationMs` | number | Server-side time to produce the response. |
| `totalResults` | number | Count of items in `results`. |
| `credit` | string | Notice that results are aggregated; clients should use per-item `creditLine`, license, and provider terms. |

### Response: `results[]` (each object)

| Field | Type | Meaning |
|-------|------|---------|
| `source` | string | Stable provider id (e.g. `unsplash`). |
| `sourceName` | string | Human-readable provider name. |
| `assetType` | string | `image` · `vector` · `icon` · `video` · `audio` · `model3d` |
| `id` | string | Id within that provider. |
| `title` | string | Display title. |
| `previewUrl` | string | Preview/thumbnail URL. |
| `downloadUrl` | string | Preferred download or asset URL when available. |
| `authors` | array | `{ "name", "profileUrl?" }` |
| `license` | object | `{ "normalized", "raw?" }` |
| `requiresAttribution` | boolean | Whether the provider expects attribution. |
| `attributionText` | string | Optional provider text. |
| `attributionUrl` | string | Optional link for attribution. |
| `creditLine` | string | Single line suitable for UI copy (creator, source, links). |
| `commercialUseAllowed` | string | `"unknown"` · `"true"` · `"false"` |
| `scraped` | boolean | Whether the row came from a scrape-based adapter. |
| `sourceUrl` | string | Canonical page for the asset on the provider’s site. |
| `rawMetadata` | object | Optional provider-specific fields. |

### Response: `errors[]` (optional)

Partial failures: `{ "source", "message" }` per provider so the rest of `results` can still be used.

---

## `GET /sources`

JSON array: `{ "name", "assetTypes" }[]` per provider. The `sources` parameter on `/search` uses provider **ids** (lowercase, e.g. `openverse`, `pexels`, `commons`, `iconify`). The public **`GET /status`** page lists ids next to each provider name.

---

## Downloading and using assets

Use the JSON fields together; **`sourceUrl`** is always the canonical page on the provider (licenses, purchase, official download).

| Field | Role |
|-------|------|
| `previewUrl` | Thumbnail / preview for UI. Long‑term hotlinking or embedding may be restricted—check the provider’s terms. |
| `downloadUrl` | Best-effort URL to fetch media or a bundle, or the closest official asset URL. Meaning **depends on `source`** (see table below). |
| `sourceUrl` | Open in browser for **license**, purchase, and **official** download when `downloadUrl` is not a direct file. |
| `rawMetadata` | Extra keys per provider (e.g. Unsplash download tracking). Read when the row’s `source` requires it. |

If **`scraped`** is `true`, prefer **`sourceUrl`** on the provider’s site for the authoritative file and terms.

### By `source` (how `downloadUrl` behaves)

| `source` | Download / use |
|----------|------------------|
| `openverse` | `downloadUrl` is the media file. Follow **Openverse** and the **original host** license; use `sourceUrl` / `attributionUrl` as needed. |
| `openverse_audio` | Same for **audio** files. |
| `commons` | `downloadUrl` is Commons file content. Follow **Wikimedia Commons** reuse and attribution rules. |
| `iconify` | Usually an **SVG** URL. License depends on the **icon set** (Iconify metadata / set author). |
| `unsplash` | `downloadUrl` is the full-resolution image. **Required for Unsplash API:** when a user **downloads** a photo, your app must **GET** the URL in **`rawMetadata.downloadLocation`** (Unsplash tracks downloads). Follow Unsplash developer terms and `creditLine`. |
| `pexels` | Direct media URL from Pexels. Follow **Pexels** API/license terms. |
| `pixabay` | Direct media URL. Follow **Pixabay** terms. |
| `flickr` | Photo file URL; **license varies** (`license`, `rawMetadata`). Use **`sourceUrl`** on Flickr for rights and restrictions. |
| `iconfinder` | Icon/file URL. **Iconfinder** license tier and attribution vary per asset. |
| `flaticon` | Icon URL. Free vs premium affects attribution (`requiresAttribution`). |
| `freepik` | Resource URL from Freepik. **Your plan** and their API terms govern use. |
| `sketchfab` | Often a **viewer / embed** URL, not a downloadable GLB. **`rawMetadata.isDownloadable`** hints if a download exists; actual files usually require a **Sketchfab** account and the model’s **license**—use **`sourceUrl`** on Sketchfab. |
| `polyhaven` | Prefer `downloadUrl` when it is a **GLTF `.zip`** bundle; **`rawMetadata.polyhavenPageUrl`** (or `sourceUrl`) is the asset page if no bundle. **CC0** assets—still follow Poly Haven’s terms. |
| `cgtrader` | Marketplace model URL or file link. **Purchase and license** are governed by **CGTrader**; use `sourceUrl` for the listing. |
| `mixkit` | Points to Mixkit; use **`sourceUrl`** for official video/audio download and terms. |
| `envato` | Points to Envato Elements; **marketplace subscription** and terms apply—**`sourceUrl`** for the asset page. |

---

## Client obligations

Display or store **`meta.credit`** and per-item **`creditLine`**, **`requiresAttribution`**, and **`license`** according to your use case and each provider’s terms. Results are **metadata and links** to third-party assets, not permission to re-host files.