> ## 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.

# Search Files

> Search through user's uploaded files using vector similarity with AI reranking.

**Namespace filtering:** Pass `namespace_ids` to restrict the search to files in specific namespaces. If omitted, all namespaces are searched.

**Process:**
1. Vector similarity search using OpenAI embeddings
2. Initial ranking by semantic similarity
3. AI reranking for improved relevance
4. Rich metadata and signed URLs for file access
5. Optional per-file AI analysis for people, places, key subjects, and key moments

Each result includes the `namespace_ids` and resolved `namespaces` the file belongs to.

Search your uploaded files using vector similarity and AI reranking.

## Overview

This endpoint searches through your uploaded file library using OpenAI embeddings for semantic similarity, followed by AI reranking for improved relevance. Results include rich metadata, signed URLs, and optional per-file analysis.

## Billing

File search consumes `search_request` usage. 1 credit covers 10 searches across YouTube or your own uploaded files.

### Search Process

1. Vector similarity search using OpenAI embeddings
2. Initial ranking by semantic similarity
3. AI reranking for improved relevance
4. Rich metadata and signed URLs for file access
5. Optional per-file AI analysis for people, places, key subjects, and key moments

## Request Body

| Parameter       | Type      | Required | Description                                                             |
| --------------- | --------- | -------- | ----------------------------------------------------------------------- |
| `query`         | string    | Yes      | Search query                                                            |
| `namespace_ids` | string\[] | No       | Restrict search to specific namespaces. If omitted, searches all files. |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.vidnavigator.com/v1/search/file" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What did the customer say about pricing?"
    }'
  ```

  ```bash cURL (with namespace filter) theme={null}
  curl -X POST "https://api.vidnavigator.com/v1/search/file" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What did the customer say about pricing?",
      "namespace_ids": ["64a1b2c3d4e5f6789abc0002"]
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vidnavigator.com/v1/search/file"
  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "query": "What did the customer say about pricing?",
      "namespace_ids": ["64a1b2c3d4e5f6789abc0002"]
  }

  response = requests.post(url, headers=headers, json=data)
  results = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.vidnavigator.com/v1/search/file', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'What did the customer say about pricing?',
      namespace_ids: ['64a1b2c3d4e5f6789abc0002']
    })
  });

  const results = await response.json();
  ```
</CodeGroup>

## Success Response

```json theme={null}
{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "file_abc123",
        "name": "client-call-march.mp4",
        "duration": 1800,
        "size": 52428800,
        "type": "video/mp4",
        "status": "completed",
        "created_at": "2026-03-10T14:00:00Z",
        "file_url": "https://storage.example.com/signed-url...",
        "namespace_ids": ["64a1b2c3d4e5f6789abc0002"],
        "namespaces": [
          { "id": "64a1b2c3d4e5f6789abc0002", "name": "Client Calls" }
        ],
        "relevance_score": 0.92,
        "timestamps": [245.5, 890.2],
        "relevant_text": "The customer mentioned the pricing was competitive but wished for a monthly option.",
        "query_answer": "The customer found pricing competitive but requested monthly billing.",
        "transcript_summary": "A 30-minute client call discussing product features, pricing, and onboarding timeline.",
        "people": [
          { "name": "John Smith", "context": "Client representative" }
        ],
        "key_subjects": [
          { "name": "Pricing", "description": "Discussion about pricing tiers and billing options" }
        ]
      }
    ],
    "query": "What did the customer say about pricing?",
    "total_found": 1,
    "explanation": "Found 1 file matching your query about customer pricing feedback."
  }
}
```


## OpenAPI

````yaml POST /search/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:
  /search/file:
    post:
      tags:
        - Search
      summary: Search uploaded files
      description: >-
        Search through user's uploaded files using vector similarity with AI
        reranking.


        **Namespace filtering:** Pass `namespace_ids` to restrict the search to
        files in specific namespaces. If omitted, all namespaces are searched.


        **Process:**

        1. Vector similarity search using OpenAI embeddings

        2. Initial ranking by semantic similarity

        3. AI reranking for improved relevance

        4. Rich metadata and signed URLs for file access

        5. Optional per-file AI analysis for people, places, key subjects, and
        key moments


        Each result includes the `namespace_ids` and resolved `namespaces` the
        file belongs to.
      operationId: searchFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: Search query
                  example: What did the customer say about pricing?
                namespace_ids:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional list of namespace IDs to restrict search scope. If
                    not provided, all namespaces are searched.
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/FileSearchResult'
                      query:
                        type: string
                      total_found:
                        type: integer
                      explanation:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    FileSearchResult:
      type: object
      properties:
        id:
          type: string
          description: File ID
        name:
          type: string
          description: File name
        duration:
          type: number
          description: Duration in seconds
        size:
          type: integer
          description: File size in bytes
        type:
          type: string
          description: MIME type
        status:
          type: string
          enum:
            - completed
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        original_file_date:
          type: string
          format: date-time
        file_url:
          type: string
          format: uri
          description: >-
            Short-lived signed Google Cloud Storage URL pointing directly at the
            file bytes. Same model as AWS S3 / CloudFront pre-signed URLs:
            time-limited and resource-scoped.
          example: >-
            https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=...
        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)
        relevance_score:
          type: number
          description: AI relevance score (0-1)
        timestamps:
          type: array
          items:
            type: number
          description: Key moment timestamps in seconds extracted from supporting evidence
        relevant_text:
          type: string
          description: Key quote from the file content
        query_answer:
          type: string
          description: Direct answer to the query
        transcript_summary:
          type: string
          description: Summary of the file's transcript
        people:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              context:
                type: string
        places:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              context:
                type: string
        key_subjects:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                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
  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
    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.

````