> ## 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.

# List Motion Templates

> Browse the official Viggle motion template catalog to find a template_id to import.

Browses Viggle's published motion template catalog — the same templates shown in the Viggle app and Discord bot. Use this to find a `template_id` before calling [Import Motion](/v1/api-reference/motions/import).

<Note>
  This endpoint passes the upstream catalog response through unchanged. The response envelope's exact field names aren't part of the versioned V1 contract — treat it as a browsing aid, read each item's `id` field, and pass that value as `template_id` to Import Motion. This is unlike every other V1 endpoint, which does commit to a fixed response shape.
</Note>

## Query parameters

All parameters are optional.

| Parameter                 | Type    | Description                                                                                                                       |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `searchKeyword`           | string  | Free-text search over the catalog.                                                                                                |
| `tagID`                   | string  | Restrict results to one tag. Resolve valid values from [List Motion Template Tags](/v1/api-reference/motions/template-tags).      |
| `multiType`               | integer | Character count in the template: `0` single-person, `1` multi-person.                                                             |
| `multiplePersonTagIdType` | integer | Multi-person tag filtering: `1` applies the default multi-person tag when `multiType=1` and no `tagID` is given; `0` disables it. |
| `type`                    | integer | Platform the template was published for: `0` Web (default), `1` Discord, `2` App.                                                 |
| `page`                    | integer | 1-based page number.                                                                                                              |
| `pageSize`                | integer | Results per page.                                                                                                                 |

```bash theme={null}
curl "https://apis.viggle.ai/v1/motion-templates?searchKeyword=dance&page=1&pageSize=20" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## Response

`200 OK` with the catalog response, passed through unchanged. Each entry carries at least an `id` — the value to use as `template_id`:

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "data": [
    { "id": "tpl_1a2b3c", "command": "wave" },
    { "id": "tpl_4d5e6f", "command": "sit" }
  ]
}
```

<Card title="Import Motion" icon="download" href="/v1/api-reference/motions/import">
  Copy a template's `id` into a Motion asset owned by your account.
</Card>


## OpenAPI

````yaml openapi.yaml GET /v1/motion-templates
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: Prepare inputs, create renders, observe progress, and retrieve results.
  - name: Credits
    description: Read the credit balance available to the calling principal.
  - name: Characters
    description: |
      Create, list, inspect, and delete reusable character assets. `type`
      selects whether creation also extracts a 3D vsplat; export its
      download URL separately once ready.
  - name: Motions
    description: |
      Create, list, inspect, and delete reusable motion assets, and import one
      from an official motion template. `type` selects whether creation also
      extracts or generates a 3D animation; export its download URL
      separately once ready.
  - name: Videos
    description: |
      Generate a MiniMax H3 text-to-video (`vid_` prefix) or a
      character-animation video from a character image and/or driving video
      (`anim_` prefix), and read the unified view over every video the
      caller owns — H3 generations, character-animation generations, and
      character+motion Renders (`render_` prefix) — merged into one
      resource.
paths:
  /v1/motion-templates:
    get:
      tags:
        - Motions
      summary: Browse the official Viggle motion template catalog
      description: |
        Passes through the published Viggle template catalog unchanged. The
        response envelope's exact shape isn't part of the versioned
        contract — read each item's `id` and pass it as `template_id` to
        [Import Motion](/v1/api-reference/motions/import). Resolve `tagID`
        values with `GET /v1/motion-template-tags`.
      operationId: listMotionTemplates
      parameters:
        - name: multiType
          in: query
          description: Character count of the template. `0` single, `1` multiple.
          required: false
          schema:
            type: integer
        - name: multiplePersonTagIdType
          in: query
          description: >
            Multi-person tag filtering. `1` applies the default multi-person tag
            when `multiType=1` and no `tagID` is given; `0` disables it.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: 1-based page number.
          required: false
          schema:
            type: integer
            minimum: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: searchKeyword
          in: query
          required: false
          schema:
            type: string
        - name: tagID
          in: query
          description: Tag to filter by, from `GET /v1/motion-template-tags`.
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: 'Platform: `0` Web (default), `1` Discord, `2` App.'
          required: false
          schema:
            type: integer
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      responses:
        '200':
          description: |
            The upstream template catalog response, passed through
            unchanged. Shape is intentionally unconstrained.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: >-
        Optional caller-supplied correlation ID, up to 128 characters. The
        service returns the effective value in the response header for tracing
        and support.
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: >-
        Optional source-channel label, up to 128 characters, used to attribute
        traffic to an SDK, integration, product surface, or internal workflow.
      schema:
        type: string
        minLength: 1
        maxLength: 128
  headers:
    RequestId:
      description: Stable request identifier for support and tracing.
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    V1Unauthorized:
      description: Missing, invalid, or expired credential.
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Service temporarily unavailable.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: >-
            Top-level draft-flow error payload containing the stable code,
            message, retry guidance, correlation ID, and error-specific details.
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - retryable
        - request_id
        - details
        - remediation
      properties:
        code:
          description: Stable error category from the draft-based render error vocabulary.
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable explanation suitable for logs or presentation to a
            developer.
        retryable:
          type: boolean
          description: >-
            Whether retrying the operation without changing its semantic input
            may succeed.
        request_id:
          type: string
          description: >-
            Correlation identifier for tracing and support. Include it when
            reporting the failure.
        details:
          type: object
          description: Error-specific structured context; available keys depend on `code`.
          additionalProperties: true
        remediation:
          description: Suggested recovery action and optional retry delay.
          allOf:
            - $ref: '#/components/schemas/ErrorRemediation'
    ErrorCode:
      description: |
        The failure vocabulary of the draft-based render flow. The resource
        operations project the same vocabulary onto the lower_snake_case codes
        described by `ResourceError`.
      type: string
      enum:
        - UNAUTHENTICATED
        - INVALID_CREDENTIAL
        - FORBIDDEN
        - INVALID_REQUEST
        - INVALID_CHARACTER
        - INVALID_MOTION
        - UNSUPPORTED_MEDIA
        - CONTENT_POLICY_VIOLATION
        - UPLOAD_REQUIRED
        - UPLOAD_MISMATCH
        - UPLOAD_EXPIRED
        - DRAFT_NOT_FOUND
        - DRAFT_ALREADY_CONSUMED
        - RENDER_NOT_FOUND
        - RENDER_NOT_CANCELLABLE
        - CHARACTER_NOT_FOUND
        - MOTION_NOT_FOUND
        - MOTION_NOT_READY
        - MOTION_TEMPLATE_NOT_FOUND
        - AVATAR_NOT_FOUND
        - ANIMATION_NOT_FOUND
        - EXTRACTION_UNAVAILABLE
        - EXTRACTION_FAILED
        - IDEMPOTENCY_KEY_REUSED
        - INSUFFICIENT_CREDITS
        - RATE_LIMITED
        - SERVICE_BUSY
        - INTERNAL_ERROR
    ErrorRemediation:
      type: object
      additionalProperties: false
      required:
        - action
        - retry_after_ms
      properties:
        action:
          type: string
          description: >-
            Suggested machine-readable or human-readable next action, such as
            retrying later, uploading media again, or correcting input.
        retry_after_ms:
          type: integer
          description: >-
            Recommended delay in milliseconds before retrying; null when no
            timed retry is advised.
          nullable: true
          format: int64
          minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: |
        Server-side SDK clients use a project API key. Remote MCP clients use
        an OAuth access token. Never expose a project API key in browser code.

````