{
  "openapi": "3.1.0",
  "info": {
    "title": "MotionVault public catalog API",
    "version": "1.0.0-beta.2",
    "description": "Public discovery is anonymous. Premium source requires membership; premium prompts require membership or a redeemed pack choice. Use a personal Bearer read key or website session. Filters run client-side; inventory is generated at build time. JSON errors preserve a human error message plus stable code and HTTP status."
  },
  "servers": [
    {
      "url": "https://motionvault.site"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/catalog": {
      "get": {
        "operationId": "getCatalogV1",
        "summary": "Read the published template and supporting asset catalog",
        "responses": {
          "200": {
            "description": "Current generated public inventory",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "503": {
            "description": "Catalog temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getCapabilitiesV1",
        "summary": "Read actual bundled agent tool schemas and workflow guides",
        "responses": {
          "200": {
            "description": "Capability metadata from the bundled package",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "503": {
            "description": "Capability inventory temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates/{id}/source": {
      "get": {
        "operationId": "getTemplateSourceV1",
        "summary": "Read free source publicly or premium source with authorised membership",
        "security": [
          {},
          {
            "PersonalReadKey": []
          },
          {
            "SessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_-]{1,120}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Original source and license/form disclosures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateSource"
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid read key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Membership or redeemed prompt required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No such published template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Catalog or source temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates/{id}/prompt": {
      "get": {
        "operationId": "getTemplatePromptV1",
        "summary": "Read a free, membership or previously redeemed pack prompt; never spends credits",
        "security": [
          {},
          {
            "PersonalReadKey": []
          },
          {
            "SessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_-]{1,120}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorised server-owned build prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatePrompt"
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid read key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Membership or prior prompt redemption required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No such published template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Prompt temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/catalog": {
      "get": {
        "operationId": "getCatalogLegacy",
        "summary": "Read the published template and supporting asset catalog",
        "responses": {
          "200": {
            "description": "Current generated public inventory",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "503": {
            "description": "Catalog temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/capabilities": {
      "get": {
        "operationId": "getCapabilitiesLegacy",
        "summary": "Read actual bundled agent tool schemas and workflow guides",
        "responses": {
          "200": {
            "description": "Capability metadata from the bundled package",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "503": {
            "description": "Capability inventory temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/templates/{id}/source": {
      "get": {
        "operationId": "getTemplateSourceLegacy",
        "summary": "Read free source publicly or premium source with authorised membership",
        "security": [
          {},
          {
            "PersonalReadKey": []
          },
          {
            "SessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_-]{1,120}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Original source and license/form disclosures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateSource"
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid read key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Membership or redeemed prompt required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No such published template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Catalog or source temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/templates/{id}/prompt": {
      "get": {
        "operationId": "getTemplatePromptLegacy",
        "summary": "Read a free, membership or previously redeemed pack prompt; never spends credits",
        "security": [
          {},
          {
            "PersonalReadKey": []
          },
          {
            "SessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_-]{1,120}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorised server-owned build prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatePrompt"
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid read key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Membership or prior prompt redemption required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No such published template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Prompt temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates/{id}/prompt": {
      "get": {
        "operationId": "getTemplatePromptCurrent",
        "summary": "Read a free, membership or previously redeemed pack prompt; never spends credits",
        "security": [
          {},
          {
            "PersonalReadKey": []
          },
          {
            "SessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_-]{1,120}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorised server-owned build prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatePrompt"
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid read key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Membership or prior prompt redemption required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No such published template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Prompt temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": [
          "error",
          "code",
          "status",
          "documentation"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "INVALID_TEMPLATE_ID",
              "TEMPLATE_NOT_FOUND",
              "CATALOG_UNAVAILABLE",
              "SOURCE_UNAVAILABLE",
              "CAPABILITIES_UNAVAILABLE"
            ]
          },
          "status": {
            "type": "integer",
            "enum": [
              400,
              404,
              503
            ]
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": false
      },
      "Asset": {
        "type": "object",
        "required": [
          "url",
          "path"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri-reference"
          },
          "path": {
            "type": "string",
            "description": "Relative path in the standalone source package."
          }
        },
        "additionalProperties": true
      },
      "Template": {
        "type": "object",
        "required": [
          "id",
          "title",
          "subtitle",
          "category",
          "engine",
          "format",
          "tags",
          "free",
          "assets"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9_-]{1,120}$"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "engine": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "free": {
            "type": "boolean"
          },
          "featured": {
            "type": "boolean"
          },
          "prompt": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "background": {
            "type": "string"
          },
          "scene": {
            "type": "string"
          },
          "assets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Asset"
            }
          },
          "procedural": {
            "type": "object",
            "required": [
              "kind"
            ],
            "properties": {
              "kind": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "cinematic": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string"
              },
              "brand": {
                "type": "string"
              },
              "poster": {
                "type": "string",
                "format": "uri-reference"
              },
              "detailPoster": {
                "type": "string",
                "format": "uri-reference"
              },
              "finalPoster": {
                "type": "string",
                "format": "uri-reference"
              },
              "video": {
                "type": "string",
                "format": "uri-reference"
              },
              "headline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "DesignAsset": {
        "type": "object",
        "required": [
          "id",
          "title",
          "library",
          "category",
          "description",
          "tags",
          "source"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "library": {
            "type": "string",
            "enum": [
              "styles",
              "ui",
              "backgrounds",
              "gradients"
            ]
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "tokens": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "Catalog": {
        "type": "object",
        "required": [
          "version",
          "generatedAt",
          "templates",
          "designAssets"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "templates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Template"
            }
          },
          "designAssets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignAsset"
            }
          }
        },
        "additionalProperties": true
      },
      "TemplateSource": {
        "type": "object",
        "required": [
          "id",
          "title",
          "html",
          "assets",
          "license",
          "licenseURL",
          "formSetup"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "html": {
            "type": "string",
            "description": "Authorised standalone HTML. Included asset references are rewritten to public URLs."
          },
          "assets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Asset"
            }
          },
          "license": {
            "type": "string"
          },
          "licenseURL": {
            "type": "string",
            "format": "uri"
          },
          "formSetup": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TemplatePrompt": {
        "type": "object",
        "required": [
          "templateId",
          "title",
          "prompt",
          "access",
          "membership",
          "alreadyRedeemed",
          "remaining"
        ],
        "properties": {
          "templateId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "access": {
            "enum": [
              "free",
              "membership",
              "pack"
            ]
          },
          "membership": {
            "type": "boolean"
          },
          "alreadyRedeemed": {
            "type": "boolean"
          },
          "orderId": {
            "type": [
              "string",
              "null"
            ]
          },
          "remaining": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "Capability": {
        "type": "object",
        "required": [
          "name",
          "description"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "inputSchema": {
            "type": "object",
            "description": "The complete actual tool JSON Schema.",
            "additionalProperties": true
          },
          "readOnly": {
            "type": "boolean"
          },
          "network": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Guide": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "execution": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "skill": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Capabilities": {
        "type": "object",
        "required": [
          "schemaVersion",
          "name",
          "version",
          "counts",
          "tools",
          "resources",
          "prompts",
          "skills",
          "agents"
        ],
        "properties": {
          "schemaVersion": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "counts": {
            "type": "object",
            "required": [
              "tools",
              "resources",
              "prompts",
              "skills",
              "agents"
            ],
            "properties": {
              "tools": {
                "type": "integer",
                "minimum": 0
              },
              "resources": {
                "type": "integer",
                "minimum": 0
              },
              "prompts": {
                "type": "integer",
                "minimum": 0
              },
              "skills": {
                "type": "integer",
                "minimum": 0
              },
              "agents": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "uri": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "mimeType": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guide"
            }
          },
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guide"
            }
          }
        },
        "additionalProperties": true
      }
    },
    "securitySchemes": {
      "PersonalReadKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Personal templates:read key; never grants billing, redemption or publishing authority."
      },
      "SessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "motionvault_session",
        "description": "Existing authenticated website session."
      }
    }
  },
  "externalDocs": {
    "description": "Examples, known beta limits, error handling and versioning",
    "url": "https://motionvault.site/developers"
  }
}