> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Motions

> Create, import, retrieve, list, and delete reusable Motion resources.

A Motion is a reusable driving action from a video. It is not a background scene. Use a Motion's `mot_...` ID as `motion_id` when creating a Render.

All endpoints in this page require `Authorization: Bearer YOUR_API_KEY`.

## Create a Motion

`POST /v1/motions`

Creates an asynchronous Motion. Send `multipart/form-data`.

| Field              | Type   | Required | Description                                   |
| ------------------ | ------ | :------: | --------------------------------------------- |
| `motion_video`     | file   |  One of  | Driving video uploaded as a file.             |
| `motion_video_url` | string |  One of  | Publicly reachable URL for the driving video. |
| `name`             | string |    No    | Optional human-readable label.                |

Provide exactly one Motion source: `motion_video` or `motion_video_url`.

Use a valid driving video that the service can read. For URL input, the URL must be reachable by Viggle's servers for the duration of the request.

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "motion_video=@dance.mp4" \
  -F "name=Dance loop"
```

### Example: create from a URL

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "motion_video_url=https://example.com/dance.mp4" \
  -F "name=Remote dance"
```

## Import a Motion template

`POST /v1/motions/import`

Imports a Motion from a Viggle template. Send a JSON request body.

| Field           | Type   | Required | Description                                                  |
| --------------- | ------ | :------: | ------------------------------------------------------------ |
| `template_id`   | string |  One of  | Template ID copied from Viggle. This is the preferred field. |
| `template_uuid` | string |  One of  | Backward-compatible alias for `template_id`.                 |
| `name`          | string |    No    | Optional label for the imported Motion.                      |

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions/import" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}'
```

The response is a Motion resource. Poll it by ID until it is `ready`.

<Note>
  `template_id` takes precedence when both template fields are sent. Send only the preferred `template_id` in new integrations.
</Note>

## Get a Motion

`GET /v1/motions/{motion_id}`

| Path parameter | Type   | Required | Description                                                             |
| -------------- | ------ | :------: | ----------------------------------------------------------------------- |
| `motion_id`    | string |    Yes   | Full Motion ID, for example `mot_550e8400-e29b-41d4-a716-446655440000`. |

```bash theme={null}
curl "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## List Motions

`GET /v1/motions`

This endpoint currently has no query parameters and returns all Motions for the current account.

```bash theme={null}
curl "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

The response uses the same `{ "data": [Resource, ...] }` shape as [List Characters](/v1/api-reference/characters).

```json theme={null}
{
  "data": [
    {
      "id": "mot_456def",
      "status": "ready",
      "name": "Dance loop",
      "progress": 100,
      "capabilities": ["video_render"],
      "created_at": "2026-07-17T10:00:00Z",
      "completed_at": "2026-07-17T10:00:20Z",
      "error": null
    }
  ]
}
```

## Delete a Motion

`DELETE /v1/motions/{motion_id}`

| Path parameter | Type   | Required | Description                                                             |
| -------------- | ------ | :------: | ----------------------------------------------------------------------- |
| `motion_id`    | string |    Yes   | Full Motion ID, for example `mot_550e8400-e29b-41d4-a716-446655440000`. |

```bash theme={null}
curl -X DELETE "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## Motion response fields

All Motion endpoints return the same resource fields as Characters: `id`, `status`, `name`, `progress`, `capabilities`, `created_at`, `completed_at`, and `error`. A Motion ID looks like `mot_550e8400-e29b-41d4-a716-446655440000`; preserve it exactly.

## Endpoint response rules

| Endpoint                         | Success status | Response                  | Parameters                                                               |
| -------------------------------- | -------------- | ------------------------- | ------------------------------------------------------------------------ |
| `POST /v1/motions`               | `200`          | Motion object             | One required video source; `name` is optional.                           |
| `POST /v1/motions/import`        | `200`          | Motion object             | One of `template_id` or `template_uuid` is required; `name` is optional. |
| `GET /v1/motions`                | `200`          | `{ "data": [Motion] }`    | No parameters.                                                           |
| `GET /v1/motions/{motion_id}`    | `200`          | Motion object             | `motion_id` is required.                                                 |
| `DELETE /v1/motions/{motion_id}` | `200`          | `{ "status": "deleted" }` | `motion_id` is required.                                                 |