{
  "openapi": "3.1.0",
  "info": {
    "title": "Pitch API",
    "version": "2.1.0",
    "description": "Create, prompt, inspect, and export projects in one usage-metered studio."
  },
  "servers": [{ "url": "https://api.trypitch.co" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/projects": {
      "post": {
        "summary": "Create a project",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProject" } } } },
        "responses": { "202": { "$ref": "#/components/responses/Project" }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" } }
      },
      "get": {
        "summary": "List projects",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }],
        "responses": { "200": { "description": "Projects and the total before limiting", "content": { "application/json": { "schema": { "type": "object", "required": ["data", "total"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "total": { "type": "integer" } } } } } } }
      }
    },
    "/v1/projects/{id}": {
      "get": { "summary": "Get a project", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "responses": { "200": { "$ref": "#/components/responses/Project" }, "404": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/projects/{id}/prompt": {
      "post": {
        "summary": "Send a usage-metered prompt",
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "minLength": 1 }, "scene": { "type": "string" }, "slide": { "type": "integer" }, "delivery": { "enum": ["queue", "steer"] } } } } } },
        "responses": { "202": { "$ref": "#/components/responses/Project" }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/projects/{id}/export": {
      "post": {
        "summary": "Start an export",
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "res": { "enum": ["720p", "1080p", "4k"] } } } } } },
        "responses": { "202": { "$ref": "#/components/responses/Export" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      },
      "get": { "summary": "Get export status", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "responses": { "200": { "$ref": "#/components/responses/Export" }, "404": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/credits": { "get": { "summary": "Get credit summary", "responses": { "200": { "description": "Balance, plan, and recent transactions" } } } },
    "/v1/pricing": { "get": { "summary": "Get usage-metering rates", "description": "Includes the 250x model-usage multiplier for turns that load a provided Pitch skill. Host compute and provider charges are not multiplied.", "security": [], "responses": { "200": { "description": "Metering rates and indicative export tiers" } } } }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Pitch pk_ API key; X-API-Key is also accepted." } },
    "parameters": { "ProjectId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } },
    "schemas": {
      "CreateProject": {
        "type": "object",
        "properties": {
          "flow": { "enum": ["launch-video", "demo-video", "deck", "recording-edit"], "deprecated": true, "description": "Compatibility hint; accepted but ignored." },
          "prompt": { "type": "string", "description": "Required unless uploads is non-empty." },
          "options": { "type": "object", "additionalProperties": true },
          "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } },
          "name": { "type": "string" }
        }
      },
      "Upload": { "type": "object", "required": ["fileBase64", "fileName"], "properties": { "fileBase64": { "type": "string" }, "fileName": { "type": "string" } } },
      "Project": {
        "type": "object",
        "required": ["id", "title", "status", "busy", "outputs"],
        "properties": {
          "id": { "type": "string" }, "title": { "type": "string" }, "status": { "enum": ["working", "ready", "failed", "empty"] }, "busy": { "type": "boolean" }, "prompt": { "type": "string" }, "options": { "type": "object" }, "outputs": { "type": "array", "items": { "type": "object" } }, "thumbnailUrl": { "type": ["string", "null"] }, "shareUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "scenes": { "type": "array" }, "slides": { "type": "array" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "ExportStatus": { "type": "object", "properties": { "running": { "type": "boolean" }, "res": { "type": ["string", "null"] }, "url": { "type": ["string", "null"] }, "progress": { "type": "number" }, "stage": { "type": "string" }, "error": { "type": ["string", "null"] } } },
      "Error": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "balance": { "type": "number" } } } } }
    },
    "responses": {
      "Project": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } },
      "Export": { "description": "Export status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportStatus" } } } },
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}