{
  "openapi": "3.1.0",
  "info": {
    "title": "Motion",
    "version": "1.0.0",
    "description": "Create and edit videos with Motion through a prompt, optional attachments, and follow-up edits. New video jobs default to GVA standard. Motion Legacy requires eligible existing-account or administrator access. Use GET /engines for available choices. Manage owner-scoped automations, schedules, run history, and analytics. Automation execution is GVA-only and defaults to standard effort."
  },
  "servers": [
    {
      "url": "https://api.motion.so/api/motion"
    }
  ],
  "security": [
    {
      "MotionApiKey": []
    }
  ],
  "paths": {
    "/sessions": {
      "post": {
        "summary": "Create a video with Motion",
        "operationId": "createMotionSession",
        "security": [
          {
            "MotionApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMotionSessionRequest"
              },
              "examples": {
                "basic": {
                  "value": {
                    "prompt": "Create a 20-second launch video."
                  }
                },
                "withReferences": {
                  "value": {
                    "prompt": "Create a short event recap video.",
                    "aspect_ratio": "9:16",
                    "duration": "30s-1min",
                    "design_md": {
                      "filename": "DESIGN.md",
                      "content": "# Design System\n\nUse a dark editorial canvas, crisp white type, and cobalt accent lines.",
                      "jsonFilename": "style-extraction.json",
                      "jsonContent": "{\"taste_dna\":{\"mood\":\"editorial precision\"}}"
                    },
                    "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "attachments": [
                      {
                        "url": "https://storage.example.com/signed/hero-image.png",
                        "name": "Hero image",
                        "type": "image",
                        "content_type": "image/png"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateMotionSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Motion API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Motion credits. Purchase credits or configure auto top-ups in the Motion frontend at https://motion.so.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsufficientCreditsError"
                }
              }
            }
          },
          "403": {
            "description": "The account lacks access to the selected or persisted engine. No generation starts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "engine_access_required",
                  "message": "Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/create-session",
          "metadata": {
            "title": "Create a video",
            "sidebarTitle": "Create a video"
          }
        }
      }
    },
    "/sessions/{job_id}/followups": {
      "post": {
        "summary": "Create a followup for a completed or input-awaiting video job",
        "operationId": "createMotionSessionFollowup",
        "security": [
          {
            "MotionApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Job ID returned by POST /sessions."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMotionSessionRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Followup accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateMotionSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Motion API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found or not owned by API key user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Followups are only allowed for completed or input-awaiting jobs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FollowupRequiresCompletedJobError"
                }
              }
            }
          },
          "403": {
            "description": "The account lacks access to the selected or persisted engine. No generation starts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "engine_access_required",
                  "message": "Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."
                }
              }
            }
          },
          "402": {
            "description": "The job is paused for credits and cannot resume until enough credits are available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "insufficient_credits",
                  "message": "Add credits before resuming this job.",
                  "status": "awaiting_user_input"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/create-followup",
          "metadata": {
            "title": "Create a followup",
            "sidebarTitle": "Create a followup"
          }
        }
      }
    },
    "/sessions/{job_id}": {
      "get": {
        "summary": "Get video job status",
        "operationId": "getMotionSessionStatus",
        "security": [
          {
            "MotionApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Job ID returned by POST /sessions."
          }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MotionJobStatus"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Motion API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found or not owned by API key user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/get-session",
          "metadata": {
            "title": "Get video job status",
            "sidebarTitle": "Get video job status"
          }
        }
      }
    },
    "/engines": {
      "get": {
        "summary": "List engines available to your account and supported efforts",
        "operationId": "listMotionEngines",
        "responses": {
          "200": {
            "description": "Engines available to the account, with exactly one marked default: GVA is the default for every authenticated account.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "engines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "engine": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "efforts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "default_effort": {
                            "type": "string"
                          },
                          "default": {
                            "type": "boolean"
                          },
                          "templates": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/list-engines",
          "metadata": {
            "title": "List engines",
            "sidebarTitle": "List engines"
          }
        }
      }
    },
    "/templates": {
      "get": {
        "summary": "List templates available to your account for an engine",
        "operationId": "listMotionTemplates",
        "parameters": [
          {
            "name": "engine",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gva",
                "motion"
              ]
            },
            "description": "Omit to use GVA."
          }
        ],
        "responses": {
          "200": {
            "description": "Published account-accessible templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "engine": {
                      "type": "string"
                    },
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "template": {
                            "type": "string"
                          },
                          "engine": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "duration_seconds": {
                            "type": "number"
                          },
                          "preview_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "thumbnail_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account lacks access to the selected or persisted engine. No generation starts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "engine_access_required",
                  "message": "Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/list-templates",
          "metadata": {
            "title": "List templates",
            "sidebarTitle": "List templates"
          }
        }
      }
    },
    "/automations/capabilities": {
      "get": {
        "summary": "Discover automation capabilities",
        "operationId": "get_automation_capabilities",
        "tags": [
          "Automations"
        ],
        "description": "Read available trigger types before creating channel automations. Twitch and Kick depend on provider configuration; inspect the saved trigger subscription for delivery readiness. Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationCapabilities"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/get-automation-capabilities"
        }
      }
    },
    "/automations": {
      "get": {
        "summary": "List automations",
        "operationId": "list_automations",
        "tags": [
          "Automations"
        ],
        "description": "Newest creation first, with ID as the stable tie-breaker. Reads do not execute work or spend credits. Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/list-automations"
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "Opaque next_cursor from the preceding page. Preserve the same filters."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 160
            },
            "description": "Case-insensitive name and prompt search."
          },
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": ""
          }
        ]
      },
      "post": {
        "summary": "Create an automation",
        "operationId": "create_automation",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:write for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:write"
            ]
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/create-automation"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAutomationRequest"
              },
              "example": {
                "name": "Daily update",
                "prompt": "Create a short daily title animation.",
                "trigger": {
                  "type": "schedule_recurring",
                  "platform": "schedule",
                  "label": "Every day",
                  "source": "Schedule",
                  "intervalMinutes": 1440
                },
                "execution": {
                  "engine": "gva",
                  "effort": "standard"
                }
              }
            }
          }
        }
      }
    },
    "/automations/{automation_id}": {
      "get": {
        "summary": "Get an automation",
        "operationId": "get_automation",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/get-automation"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          }
        ]
      },
      "patch": {
        "summary": "Update or pause an automation",
        "operationId": "update_automation",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:write for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent execution edit: update_conflict. Read the automation again before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/update-automation"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAutomationRequest"
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete an automation",
        "operationId": "delete_automation",
        "tags": [
          "Automations"
        ],
        "description": "Deletes the saved definition. Does not cancel work already running in a Motion chat. Requires motion:automations:write for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationDeleted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/delete-automation"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          }
        ]
      }
    },
    "/automations/{automation_id}/run": {
      "post": {
        "summary": "Run an automation now",
        "operationId": "run_automation",
        "tags": [
          "Automations"
        ],
        "description": "Schedule automations only; channel automations require a real source event. New invocations open a new Motion chat and may use credits. Send no body. Requires motion:automations:write for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:write"
            ]
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationInvocation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "200": {
            "description": "Existing invocation returned for a reused UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationInvocation"
                }
              }
            }
          },
          "409": {
            "description": "automation_paused: resume before running.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/run-automation"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "New UUID for each intentional run. Reuse the same UUID after a lost response to avoid duplicate work."
          }
        ]
      }
    },
    "/automations/{automation_id}/runs": {
      "get": {
        "summary": "List automation runs",
        "operationId": "list_automation_runs",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRunPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/list-automation-runs"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "Opaque nextCursor from the previous page. Omit on the first page."
          }
        ]
      }
    },
    "/automations/{automation_id}/runs/{run_id}": {
      "get": {
        "summary": "Get an automation run",
        "operationId": "get_automation_run",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRunDetail"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/get-automation-run"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          },
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Run ID from this automation."
          }
        ]
      }
    },
    "/automations/{automation_id}/runs/{run_id}/retry": {
      "post": {
        "summary": "Retry an automation run",
        "operationId": "retry_automation_run",
        "tags": [
          "Automations"
        ],
        "description": "Only failed or blocked runs. Reuses the original source event. Repeating the same failed run ID returns its existing replacement attempt. Send no body. Requires motion:automations:write for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:write"
            ]
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationInvocation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "409": {
            "description": "automation_paused: resume before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/retry-automation-run"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          },
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Run ID from this automation."
          }
        ]
      }
    },
    "/automations/{automation_id}/analytics": {
      "get": {
        "summary": "Get automation analytics",
        "operationId": "get_automation_analytics",
        "tags": [
          "Automations"
        ],
        "description": " Requires motion:automations:read for OAuth tokens. API keys use the owner account permissions. Automation access must be enabled for the account and environment. See /guides/automations. Automations execute only with GVA; Claude supports reads, pause, and delete only.",
        "security": [
          {
            "MotionApiKey": []
          },
          {
            "MotionOAuth": [
              "motion:automations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or cursor; read the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or wrong-audience credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "403": {
            "description": "Missing OAuth scope, account automation access, or engine access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable environment, or automation/run not owned by this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/reference/get-automation-analytics"
        },
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "ID returned by list or create."
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 7,
              "maximum": 90,
              "default": 30
            },
            "description": ""
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "MotionApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Motion API key (motion_ prefix), authenticated as its owner. Account and engine permissions still apply."
      },
      "MotionOAuth": {
        "type": "oauth2",
        "description": "OAuth token audience must be https://mcp.motion.so/mcp for REST. Tokens for restricted MCP profiles cannot be reused here. Existing grants require reauthorization to add automation scopes.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.motion.so/oauth/authorize",
            "tokenUrl": "https://mcp.motion.so/oauth/token",
            "scopes": {
              "motion:automations:read": "Read automation definitions, capabilities, runs, and analytics.",
              "motion:automations:write": "Create, edit, delete, invoke, and retry automations."
            }
          }
        }
      }
    },
    "schemas": {
      "CreateMotionSessionRequest": {
        "type": "object",
        "description": "Creates a durable video job owned by the API key user. Requires available Motion credits on that user's account. Credits and auto top-ups are managed at https://motion.so, not through the API.",
        "required": [
          "prompt"
        ],
        "additionalProperties": false,
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 12000
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/MotionAspectRatio"
          },
          "duration": {
            "$ref": "#/components/schemas/MotionDurationBucket"
          },
          "design_system_id": {
            "$ref": "#/components/schemas/MotionDesignSystemId"
          },
          "design_md": {
            "description": "Pro/Max custom DESIGN.md content, optionally with a companion style extraction JSON artifact. If both design_system_id and design_md are sent, design_md content is used.",
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 200000
              },
              {
                "$ref": "#/components/schemas/MotionDesignMd"
              }
            ]
          },
          "style_reference_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Optional YouTube style reference URL."
          },
          "attachments": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/MotionAttachment"
            }
          },
          "engine": {
            "type": "string",
            "description": "Video engine. New jobs default to gva. Motion Legacy requires eligible account access. Use GET /engines for available choices. Omitting engine selects GVA even with the deprecated mode field. Existing projects retain their engine."
          },
          "effort": {
            "type": "string",
            "enum": [
              "standard",
              "extended",
              "light",
              "medium",
              "high"
            ],
            "description": "GVA: standard (default) or extended. Motion: light, medium (default), or high. Legacy GVA light/medium map to standard; high maps to extended. Follow-ups retain the current effort when omitted."
          },
          "mode": {
            "type": "string",
            "enum": [
              "light",
              "medium",
              "high"
            ],
            "deprecated": true,
            "description": "Alias for effort. Mode-only creation selects GVA. Existing projects retain their engine. Must resolve to the same effort if both are supplied. For GVA, light/medium map to standard and high maps to extended."
          },
          "template": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
            "description": "Identifier from the selected engine template catalog. Set at creation; requires Pro or Max."
          }
        }
      },
      "MotionAspectRatio": {
        "type": "string",
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:5",
          "21:9"
        ],
        "description": "Target video aspect ratio."
      },
      "MotionDurationBucket": {
        "type": "string",
        "enum": [
          "<10s",
          "10-30s",
          "30s-1min",
          "1-5min"
        ],
        "description": "Target video duration bucket."
      },
      "MotionDesignSystemId": {
        "type": "string",
        "enum": [
          "mosaic",
          "apple",
          "claude",
          "cursor",
          "linear",
          "vercel",
          "stripe",
          "figma",
          "notion",
          "spotify",
          "supabase",
          "raycast",
          "framer",
          "resend",
          "mintlify",
          "sentry",
          "tesla",
          "nike",
          "shopify",
          "airbnb",
          "posthog"
        ],
        "description": "Pro/Max built-in DESIGN.md preset to apply."
      },
      "MotionDesignMd": {
        "type": "object",
        "required": [
          "content"
        ],
        "additionalProperties": false,
        "properties": {
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "default": "DESIGN.md"
          },
          "sourceUrl": {
            "type": "string",
            "maxLength": 2048,
            "description": "Optional source website URL for imported style extraction context."
          },
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200000,
            "description": "Pro/Max markdown design system guidance saved as DESIGN.md for the job."
          },
          "jsonFilename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "default": "style-extraction.json",
            "description": "Optional companion style extraction JSON filename."
          },
          "jsonContent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200000,
            "description": "Optional structured style extraction JSON saved alongside DESIGN.md for agent context."
          }
        }
      },
      "MotionAttachment": {
        "type": "object",
        "required": [
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 4096,
            "description": "Publicly accessible signed URL."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 240
          },
          "type": {
            "type": "string",
            "enum": [
              "image",
              "video",
              "audio",
              "file"
            ]
          },
          "content_type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        }
      },
      "CreateMotionSessionResponse": {
        "type": "object",
        "required": [
          "job_id",
          "status",
          "status_url"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued"
            ]
          },
          "status_url": {
            "type": "string",
            "format": "uri",
            "description": "Authenticated public API polling URL for GET /sessions/{job_id}. This is not a Motion app page."
          },
          "chat_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Motion app chat URL for a human to open, inspect, or continue the run. Null only for legacy flows where no chat is available."
          },
          "engine": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null when engine details are unavailable to this account."
          },
          "effort": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "standard",
              "extended",
              "light",
              "medium",
              "high",
              null
            ],
            "description": "Null when engine details are unavailable to this account."
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "MotionJobStatus": {
        "type": "object",
        "required": [
          "job_id",
          "status",
          "created_at",
          "updated_at",
          "completed_at",
          "error",
          "pending_user_input",
          "output"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "created",
              "running",
              "awaiting_user_input",
              "completed",
              "failed"
            ]
          },
          "chat_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Motion app chat URL for a human to open, inspect, or continue the run. Null for legacy jobs without a Motion agent chat."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "pending_user_input": {
            "type": "boolean"
          },
          "output": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotionJobOutput"
              },
              {
                "type": "null"
              }
            ],
            "description": "Download readiness state. There is no separate public output/download endpoint; poll this status response until output.status is completed and output.download_url is non-null."
          },
          "sources": {
            "type": "array",
            "description": "Additive source-asset audit list for media currently used in the composition. Empty when no source assets are recorded yet. Internal storage paths, filenames, and GCS URIs are not exposed.",
            "items": {
              "$ref": "#/components/schemas/MotionCompositionSource"
            }
          },
          "engine": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null when engine details are unavailable to this account."
          },
          "effort": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "standard",
              "extended",
              "light",
              "medium",
              "high",
              null
            ],
            "description": "Null when engine details are unavailable to this account."
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "MotionCompositionSourceUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "start_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Timeline start time in seconds when known."
          },
          "end_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Timeline end time in seconds when known."
          },
          "duration_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Timeline duration in seconds when known."
          },
          "scene_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "scene_index": {
            "type": [
              "number",
              "null"
            ]
          },
          "slot_key": {
            "type": [
              "string",
              "null"
            ]
          },
          "element_tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Composition element tag such as img, video, audio, or source."
          },
          "composition_file": {
            "type": [
              "string",
              "null"
            ]
          },
          "composition_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "track_index": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "MotionCompositionSource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "source_kind",
          "provider",
          "provider_asset_id",
          "source_url",
          "display_url",
          "source_domain",
          "media_type",
          "title",
          "credit",
          "rights_status",
          "usages",
          "source_metadata",
          "rights_metadata"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "source_kind": {
            "type": "string",
            "enum": [
              "licensed_library",
              "article",
              "web_search",
              "web",
              "connector",
              "upload",
              "generated",
              "unknown"
            ],
            "description": "How the asset was acquired."
          },
          "provider": {
            "type": "string",
            "description": "Provider or origin, such as getty, pexels, perplexity, github, or an article domain."
          },
          "provider_asset_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Provider-specific asset ID when available."
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Canonical public source URL when available."
          },
          "display_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Preview/display URL when available."
          },
          "source_domain": {
            "type": [
              "string",
              "null"
            ]
          },
          "media_type": {
            "type": "string",
            "enum": [
              "image",
              "video",
              "audio",
              "file",
              "unknown"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "credit": {
            "type": [
              "string",
              "null"
            ]
          },
          "rights_status": {
            "type": "string",
            "enum": [
              "licensed",
              "public",
              "restricted",
              "user_provided",
              "generated",
              "unknown"
            ],
            "description": "Best-known rights category for the source asset."
          },
          "usages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MotionCompositionSourceUsage"
            }
          },
          "source_metadata": {
            "type": "object",
            "description": "Provider/source-specific public metadata. Shape varies by source kind and provider.",
            "additionalProperties": true
          },
          "rights_metadata": {
            "type": "object",
            "description": "Provider/license-specific rights metadata. Shape varies by source kind and provider.",
            "additionalProperties": true
          }
        }
      },
      "MotionJobOutput": {
        "type": "object",
        "required": [
          "status",
          "download_url",
          "expires_at",
          "completed_at",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "queued",
              "processing",
              "completed",
              "failed",
              "outdated"
            ]
          },
          "download_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Signed MP4 download URL. Present only when status is completed."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Expiration timestamp for download_url."
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "InsufficientCreditsError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "insufficient_credits"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "minimum_required_credits": {
            "type": "number"
          },
          "current_balance": {
            "type": "number"
          }
        },
        "description": "Returned when the API key owner's account does not have enough Motion credits. Purchase credits or configure auto top-ups in the Motion frontend at https://motion.so."
      },
      "FollowupRequiresCompletedJobError": {
        "type": "object",
        "required": [
          "error",
          "message",
          "status"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "followup_requires_completed_job"
          },
          "message": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "description": "Returned when creating a followup for a job that is neither completed nor awaiting user input."
      },
      "AutomationTrigger": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "schedule_once",
              "schedule_recurring",
              "youtube_video_uploaded",
              "twitch_stream_ended",
              "kick_stream_ended"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "schedule",
              "youtube",
              "twitch",
              "kick"
            ]
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "description": "Use Schedule for schedules; otherwise a channel URL, handle, or YouTube channel ID."
          },
          "timezone": {
            "type": "string",
            "maxLength": 100,
            "description": "Display timezone. Recurring intervals use elapsed minutes, not wall-clock cron scheduling."
          },
          "intervalMinutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 525600,
            "description": "Required for recurring schedules."
          },
          "runAt": {
            "type": "string",
            "format": "date-time",
            "description": "Required for one-time schedules. Include a UTC offset and choose a future timestamp."
          }
        },
        "required": [
          "type",
          "platform",
          "label",
          "source"
        ],
        "additionalProperties": false,
        "description": "Match platform to trigger type. Discover environment availability with GET /automations/capabilities."
      },
      "AutomationMemory": {
        "type": "object",
        "properties": {
          "rememberProcessedItems": {
            "type": "boolean"
          },
          "includePreviousRuns": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "compactAfterRuns": {
            "type": "integer",
            "minimum": 5,
            "maximum": 100
          }
        },
        "required": [
          "rememberProcessedItems",
          "includePreviousRuns",
          "compactAfterRuns"
        ],
        "additionalProperties": false
      },
      "AutomationConnectorCondition": {
        "type": "object",
        "properties": {
          "eventTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "schedule_once",
                "schedule_recurring",
                "youtube_video_uploaded",
                "twitch_stream_ended",
                "kick_stream_ended"
              ]
            }
          },
          "payloadField": {
            "type": "string",
            "maxLength": 200
          },
          "equals": {
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "AutomationConnectorGrant": {
        "type": "object",
        "properties": {
          "connectorId": {
            "type": "string",
            "enum": [
              "github",
              "notion",
              "figma",
              "google-drive",
              "dropbox",
              "getty"
            ]
          },
          "access": {
            "type": "string",
            "enum": [
              "read"
            ]
          },
          "resources": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            }
          },
          "condition": {
            "$ref": "#/components/schemas/AutomationConnectorCondition"
          }
        },
        "required": [
          "connectorId",
          "access",
          "resources"
        ],
        "additionalProperties": false
      },
      "AutomationConnectorPolicy": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "none",
              "fixed",
              "conditional"
            ]
          },
          "onUnavailable": {
            "type": "string",
            "enum": [
              "block",
              "run_without"
            ]
          },
          "grants": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "$ref": "#/components/schemas/AutomationConnectorGrant"
            }
          }
        },
        "required": [
          "mode",
          "onUnavailable",
          "grants"
        ],
        "additionalProperties": false,
        "description": "Uses existing connected accounts and permissions; this request cannot connect an account or grant access."
      },
      "AutomationExecution": {
        "type": "object",
        "properties": {
          "engine": {
            "type": "string",
            "enum": [
              "gva"
            ],
            "description": "Automations execute only with GVA."
          },
          "effort": {
            "type": "string",
            "enum": [
              "standard",
              "extended"
            ],
            "description": "Defaults to standard. Motion Legacy efforts are unavailable for automations."
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Supply engine or effort. Engine changes use the new engine default when effort is omitted."
      },
      "CreateAutomationRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000,
            "description": "Self-contained instructions used for every future invocation."
          },
          "trigger": {
            "$ref": "#/components/schemas/AutomationTrigger"
          },
          "memory": {
            "$ref": "#/components/schemas/AutomationMemory"
          },
          "connectorPolicy": {
            "$ref": "#/components/schemas/AutomationConnectorPolicy"
          },
          "maxConcurrentRuns": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1
          },
          "maxRunsPerHour": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 4
          },
          "execution": {
            "$ref": "#/components/schemas/AutomationExecution"
          },
          "outputKind": {
            "type": "string",
            "enum": [
              "video",
              "text",
              "auto"
            ],
            "default": "video"
          }
        },
        "required": [
          "name",
          "prompt",
          "trigger"
        ],
        "additionalProperties": false,
        "description": "Creates an enabled automation. Defaults: GVA standard, memory {rememberProcessedItems:true,includePreviousRuns:5,compactAfterRuns:20}, no connectors, one concurrent run and four runs per hour. Creation is not idempotent; do not blindly repeat a request after a lost response."
      },
      "UpdateAutomationRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000,
            "description": "Self-contained instructions used for every future invocation."
          },
          "trigger": {
            "$ref": "#/components/schemas/AutomationTrigger"
          },
          "memory": {
            "$ref": "#/components/schemas/AutomationMemory"
          },
          "connectorPolicy": {
            "$ref": "#/components/schemas/AutomationConnectorPolicy"
          },
          "maxConcurrentRuns": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1
          },
          "maxRunsPerHour": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 4
          },
          "execution": {
            "$ref": "#/components/schemas/AutomationExecution"
          },
          "enabled": {
            "type": "boolean",
            "description": "False pauses future scheduling; true resumes it. Does not cancel an already running invocation."
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Supply at least one editable field. Nested objects replace their saved value; include all required nested fields. outputKind is creation-only. Execution changes can return 409 update_conflict; reread before retrying."
      },
      "AutomationRun": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "skipped",
              "failed",
              "blocked"
            ]
          },
          "motionAgentChatId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null until a Motion chat is created. Open https://motion.so/agent?chat={motionAgentChatId} to inspect the run."
          },
          "queuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "attempt": {
            "type": "integer"
          },
          "resultSummary": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "status",
          "motionAgentChatId",
          "queuedAt"
        ],
        "additionalProperties": true,
        "description": "Read view can also include event context, logs, artifacts, and connector snapshots. An accepted or completed agent run is not proof of a downloadable video; inspect saved exports in its Motion chat."
      },
      "Automation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "prompt": {
            "type": "string"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "platform": {
                "type": "string"
              },
              "source": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "platform",
              "source"
            ],
            "additionalProperties": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "nextRunAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "runs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AutomationRun"
            }
          },
          "memory": {
            "$ref": "#/components/schemas/AutomationMemory"
          },
          "connectorPolicy": {
            "$ref": "#/components/schemas/AutomationConnectorPolicy"
          },
          "maxConcurrentRuns": {
            "type": "integer"
          },
          "maxRunsPerHour": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "prompt",
          "trigger",
          "createdAt",
          "updatedAt",
          "nextRunAt",
          "runs"
        ],
        "additionalProperties": true,
        "description": "Owner-scoped read view. Read responses can include additional saved context and history. Use the dedicated run-history endpoint for pagination. Read fields are not accepted as write inputs."
      },
      "AutomationEnvelope": {
        "type": "object",
        "properties": {
          "automation": {
            "$ref": "#/components/schemas/Automation"
          }
        },
        "required": [
          "automation"
        ],
        "additionalProperties": false
      },
      "AutomationList": {
        "type": "object",
        "properties": {
          "automations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Automation"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "automations",
          "has_more",
          "next_cursor"
        ],
        "additionalProperties": false
      },
      "AutomationRunPage": {
        "type": "object",
        "properties": {
          "runs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AutomationRun"
            }
          },
          "total": {
            "type": "number"
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "runs",
          "total",
          "nextCursor"
        ],
        "additionalProperties": false
      },
      "AutomationSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "runId": {
            "type": "string"
          },
          "motionAgentChatId": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "runId",
          "motionAgentChatId",
          "status"
        ],
        "additionalProperties": true
      },
      "AutomationRunDetail": {
        "type": "object",
        "properties": {
          "automation": {
            "$ref": "#/components/schemas/Automation"
          },
          "run": {
            "$ref": "#/components/schemas/AutomationRun"
          },
          "session": {
            "$ref": "#/components/schemas/AutomationSession"
          }
        },
        "required": [
          "automation",
          "run",
          "session"
        ],
        "additionalProperties": false
      },
      "AutomationInvocation": {
        "type": "object",
        "properties": {
          "automation": {
            "$ref": "#/components/schemas/Automation"
          },
          "run": {
            "$ref": "#/components/schemas/AutomationRun"
          },
          "session": {
            "$ref": "#/components/schemas/AutomationSession"
          },
          "deduplicated": {
            "type": "boolean"
          }
        },
        "required": [
          "automation",
          "run",
          "session",
          "deduplicated"
        ],
        "additionalProperties": false
      },
      "AutomationCapabilities": {
        "type": "object",
        "properties": {
          "triggers": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "schedule_once",
                "schedule_recurring",
                "youtube_video_uploaded",
                "twitch_stream_ended",
                "kick_stream_ended"
              ]
            }
          },
          "operations": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "capabilities",
                "list",
                "get",
                "create",
                "update",
                "delete",
                "run",
                "runs",
                "run_detail",
                "retry",
                "analytics"
              ]
            }
          },
          "run_destination": {
            "type": "string",
            "enum": [
              "new_chat"
            ]
          },
          "schedule_semantics": {
            "type": "string",
            "enum": [
              "elapsed_minutes"
            ]
          },
          "execution_engine": {
            "type": "string",
            "enum": [
              "gva"
            ]
          },
          "default_effort": {
            "type": "string",
            "enum": [
              "standard"
            ]
          },
          "execution_supported": {
            "type": "boolean"
          },
          "update_constraints": {
            "type": "string"
          }
        },
        "required": [
          "triggers",
          "operations",
          "run_destination",
          "schedule_semantics",
          "execution_engine",
          "default_effort",
          "execution_supported",
          "update_constraints"
        ],
        "additionalProperties": false
      },
      "AutomationAnalytics": {
        "type": "object",
        "properties": {
          "days": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "buckets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "completed": {
                  "type": "number"
                },
                "failed": {
                  "type": "number"
                },
                "skipped": {
                  "type": "number"
                },
                "inProgress": {
                  "type": "number"
                },
                "total": {
                  "type": "number"
                }
              },
              "required": [
                "date",
                "completed",
                "failed",
                "skipped",
                "inProgress",
                "total"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "days",
          "total",
          "buckets"
        ],
        "additionalProperties": false
      },
      "AutomationError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "AutomationDeleted": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "deleted"
        ],
        "additionalProperties": false
      }
    }
  }
}
