{
  "openapi": "3.0.3",
  "info": {
    "title": "Get The Vid Assistant Download Tool",
    "version": "3.0.0",
    "description": "Resolve media download requests, return missing-input questions or clear errors. Give the user returned links. Do not fabricate downloads or silently change quality. Only download media the user owns or has permission to save."
  },
  "servers": [
    {
      "url": "https://getthevid.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/agent/link": {
      "get": {
        "summary": "Resolve a user media request or return questions for missing choices",
        "description": "Resolve the post once and return open_url for the website with the requested format and quality selected. This is a ready-to-use page, not a direct media file or completed download. Ask for missing choices; never silently change resolution.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Public media page URL",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "MP4 with audio, MP3 audio, or actual post images",
            "schema": {
              "type": "string",
              "enum": [
                "video",
                "audio",
                "image",
                "mp4",
                "mp3"
              ]
            }
          },
          {
            "name": "quality",
            "in": "query",
            "required": false,
            "description": "Required for video: recommended (prefer combined), best (highest MP4), lowest, or exact 1080p/2160p etc. Ignored for MP3/images.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "slide",
            "in": "query",
            "required": false,
            "description": "Carousel video number; ask if ambiguous.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "image",
            "in": "query",
            "required": false,
            "description": "Photo number or all; ask if multiple photos and unspecified.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ready-to-use website link or follow-up questions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unavailable media, requested quality or item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "413": {
            "description": "File exceeds limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "429": {
            "description": "Request budget exhausted; observe Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "503": {
            "description": "Source verification, throttling, timeout or converter unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          }
        },
        "operationId": "getDownloadLink"
      }
    },
    "/api/agent/open/{token}": {
      "get": {
        "summary": "Get short-lived resolved metadata for a website handoff",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved post metadata and exact selection"
          },
          "404": {
            "description": "Handoff expired"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentResponse": {
        "type": "object",
        "required": [
          "ok",
          "status"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "needs_input",
              "error"
            ]
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "question": {
                  "type": "string"
                },
                "choices": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      }
                    ]
                  }
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "retry_after": {
            "type": "integer"
          },
          "available_qualities": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "quality": {
            "type": "string"
          },
          "has_sound": {
            "type": "boolean",
            "nullable": true
          },
          "audio_language": {
            "type": "string",
            "nullable": true
          },
          "requires_processing": {
            "type": "boolean"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "open_url": {
            "type": "string",
            "format": "uri",
            "description": "Open this website page to download; it is not a direct file URL."
          },
          "delivery": {
            "type": "string",
            "enum": [
              "browser"
            ]
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Provider-neutral assistant workflow and capabilities",
    "url": "https://getthevid.com/llms.txt"
  }
}