> ## Documentation Index > Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt > Use this file to discover all available pages before exploring further. # Analyze Uploaded File > Analyze an uploaded file and return comprehensive analysis results with intelligent caching. **Behavior:** - If no query provided: Returns summary analysis (cached if available) - If query provided: Returns both summary (from cache if available) and fresh question analysis Optional: set `transcript_text=true` to return the transcript as a single text string instead of an array of segments. Run AI-powered analysis on a previously uploaded audio/video file. ## Overview Similar to **Analyze Video**, but operates on files in your library. ## Request Body * `file_id` (string, required): ID of the uploaded file to analyze * `query` (string, optional): Ask a specific question about the content ## Billing File analysis consumes `analysis_request` units based on context size. One unit covers up to **15,000 total tokens**, and longer contexts are billed with `ceil(total_tokens / 15000)`. For example, an analysis that uses 17,000 total tokens consumes 2 `analysis_request` units. ## Example Request ```bash cURL theme={null} curl -X POST "https://api.vidnavigator.com/v1/analyze/file" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "file_id": "file_abc123", "query": "Summarize the key points" }' ``` ## OpenAPI ````yaml POST /analyze/file openapi: 3.0.3 info: title: VidNavigator Developer API description: >- The VidNavigator Developer API provides programmatic access to video analysis, transcription, and search capabilities. ## Authentication All endpoints require API key authentication via the `X-API-Key` header: ``` X-API-Key: YOUR_API_KEY ``` ## Rate Limits Check the documentation for the rate limits for each endpoint. ## Error Handling The API uses standard HTTP status codes and returns error responses in JSON format: ```json { "status": "error", "error": "error_type", "message": "Human readable error message" } ``` version: 1.0.0 contact: name: VidNavigator Support url: https://vidnavigator.com/support email: support@vidnavigator.com license: name: Proprietary url: https://vidnavigator.com/terms servers: - url: https://api.vidnavigator.com/v1 description: Production server security: - ApiKeyAuth: [] tags: - name: Transcripts description: Extract transcripts from online videos - name: TikTok description: Scrape TikTok profile metadata and per-video stats - name: Files description: Manage uploaded audio/video files - name: Analysis description: AI-powered content analysis - name: Extraction description: >- Extract structured data from video and file transcripts using custom schemas - name: Namespaces description: Organize uploaded files into namespaces (folders) - name: Search description: Search videos and files using AI - name: System description: System health and information - name: Tweet Analysis description: Extract structured claims and metadata from X/Twitter tweets paths: /analyze/file: post: tags: - Analysis summary: Analyze uploaded file description: >- Analyze an uploaded file and return comprehensive analysis results with intelligent caching. **Behavior:** - If no query provided: Returns summary analysis (cached if available) - If query provided: Returns both summary (from cache if available) and fresh question analysis Optional: set `transcript_text=true` to return the transcript as a single text string instead of an array of segments. operationId: analyzeFile requestBody: required: true content: application/json: schema: type: object required: - file_id properties: file_id: type: string description: ID of the uploaded file to analyze query: type: string description: Optional question about the file content example: What is discussed in this file? transcript_text: type: boolean default: false description: >- When true, returns the transcript as a single plain-text string instead of an array of segments. responses: '200': description: File analyzed successfully content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: file_info: $ref: '#/components/schemas/FileInfo' transcript: $ref: '#/components/schemas/TranscriptOutput' transcript_analysis: $ref: '#/components/schemas/AnalysisResult' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/FileNotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: FileInfo: type: object properties: id: type: string description: Unique file identifier name: type: string description: File name size: type: integer description: File size in bytes type: type: string description: MIME type duration: type: number description: Duration in seconds status: type: string enum: - pending - processing - completed - failed - cancelled description: Processing status created_at: type: string format: date-time description: Upload timestamp updated_at: type: string format: date-time description: Last update timestamp original_file_date: type: string format: date-time description: Original file creation date has_transcript: type: boolean description: Whether transcript is available error_message: type: string description: Error message if processing failed namespace_ids: type: array items: type: string description: IDs of the namespaces this file belongs to namespaces: type: array items: $ref: '#/components/schemas/NamespaceRef' description: Resolved namespaces this file belongs to (with names) TranscriptOutput: description: >- Transcript output. By default it is an array of segments. When `transcript_text=true`, it is returned as a single plain-text string. oneOf: - type: array items: $ref: '#/components/schemas/TranscriptSegment' - type: string AnalysisResult: type: object properties: summary: type: string description: Content summary people: type: array items: type: object properties: name: type: string context: type: string description: People mentioned in the content places: type: array items: type: object properties: name: type: string context: type: string description: Places mentioned in the content key_subjects: type: array items: type: object properties: name: type: string description: type: string importance: type: string description: Key subjects/topics discussed timestamp: type: number description: Key moment timestamp (if applicable) relevant_text: type: string description: Key quote from the content (for questions) query_answer: type: object description: Answer to the query (only when query is provided) properties: answer: type: string best_segment_index: type: integer relevant_segments: type: array items: type: string NamespaceRef: type: object description: Resolved namespace reference with ID and display name properties: id: type: string description: Namespace identifier name: type: string description: Namespace display name TranscriptSegment: type: object properties: text: type: string description: Transcript text for this segment start: type: number description: Start time in seconds end: type: number description: End time in seconds responses: BadRequest: description: Bad request - invalid parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: string message: type: string PaymentRequired: description: Usage limit exceeded - upgrade required content: application/json: schema: type: object properties: status: type: string enum: - error error: type: string enum: - limit_exceeded message: type: string AccessDenied: description: Access denied - insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: string enum: - access_denied message: type: string FileNotFound: description: File not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: string enum: - file_not_found message: type: string InternalServerError: description: Internal server error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: string enum: - internal_server_error message: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API key authentication. Include your VidNavigator API key in the X-API-Key header. ````