# Search the videos

> Gallery videos matching every facet given. Several values in one facet are alternatives (`color=red,orange` is red or orange); different facets all apply. The answer says how each model and creator was read, and, when nothing matches several facets, how many videos each matches alone.

`GET https://motionvideo.xyz/api/catalog/search`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | No | Keywords; every word must appear in the title, the creator's handle, the prompt or the categories. |
| `category` | query | array of string | No | Gallery categories, any of them. |
| `model` | query | array of string | No | Models, any of them: a name (`Opus 5.5`), a full name (`Claude Opus 5.5`), a family (`Gemini`) or a bare version (`5.5`, every model with it). |
| `color` | query | array of string | No | Named colours the video contains, matched like the `/color/{color}` pages. |
| `colorMatch` | query | string | No | With several colours: `any` (default) or `all` of them. |
| `creator` | query | array of string | No | Creators, any of them: X handles (with or without `@`) or display names, ignoring case. |
| `type` | query | string | No | Only videos sharing a prompt, or a skill. |
| `sort` | query | string | No | By post date. Defaults to `newest`. |
| `limit` | query | integer | No | Results per page, 1 to 50. Defaults to 12. |
| `offset` | query | integer | No | Results to skip, for the next page. Defaults to 0. |

## Example request

```bash
curl https://motionvideo.xyz/api/catalog/search
```

## Responses

### 200

The matching videos, without prompts.

| Header | Description |
| --- | --- |
| `Cache-Control` | Browsers reuse a response for 5 minutes and shared caches for an hour, then may serve it stale for up to a day while they revalidate. Value: `public, max-age=300, s-maxage=3600, stale-while-revalidate=86400` |

Body (`application/json`):

- `total` (integer, required): Matches before paging.
- `limit` (integer, required)
- `offset` (integer, required)
- `videos` (array of VideoSummary, required)
  - `slug` (string, required)
  - `title` (string, required)
  - `date` (string (date), required)
  - `tags` (array of string, required) One of `prompt`, `skill`.
  - `contentTags` (array of string, required) One of `product-ui`, `phone`, `charts`, `diagrams`, `kinetic-type`, `shapes`, `particles`, `characters`, `photos`, `music`, `code`.
  - `promptShared` (boolean, required)
  - `handle` (string, required)
  - `creatorName` (string)
  - `avatar` (string (uri), required)
  - `poster` (string (uri), required)
  - `preview` (string (uri), required)
  - `video` (string (uri), required)
  - `width` (integer, required)
  - `height` (integer, required)
  - `description` (string)
  - `model` (string) One of `Opus 5.5`, `Fable 5`, `Fable 5.1`, `Fable 5.2`, `Fable 5.5`, `Mythos 5`, `Mythos 5.2`, `GPT-6 Astra`, `Gemini 4 Argon`, `Gemini 4 Carbon`, `Gemini 4 Neon`.
  - `stack` (string)
  - `effort` (string) One of `medium`, `high`, `max`.
  - `iterations` (string) One of `one-shot`, `few-rounds`, `many-rounds`.
  - `colorNames` (array of string, required): Named colours the video contains. One of `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `brown`, `black`, `white`, `gray`.
  - `pageUrl` (string (uri), required): The video's page in English.
- `resolved` (object, required)
  - `models` (array of object, required): How each requested model was read, in request order.
    - `requested` (string, required): As sent.
    - `matched` (array of string, required): The catalog models it matched; empty when none, which matches no videos.
  - `creators` (array of object, required): How each requested creator was read, in request order.
    - `requested` (string, required): As sent.
    - `matched` (array of string, required): The catalog creators it matched; empty when none, which matches no videos.
    - `similar` (array of string, required): With no match: up to five handles containing what was sent.
- `perFacet` (array of object): Only with no match and several facets: how many videos each facet matches alone.
  - `facet` (string, required) One of `q`, `category`, `model`, `color`, `creator`, `type`.
  - `total` (integer, required)

### 400

A parameter is unknown or has a value it can't take.

Body (`application/json`):

- `error` (string, required) One of `invalid_parameter`.
- `parameter` (string, required)
- `message` (string, required)
- `allowed` (array of string): The values the parameter can take, when it has a fixed set.