> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.video/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Clips

> Search video clips using natural language queries

## POST /api/v1/search/query

Search for video clips using natural language queries. Returns relevant clips with timestamps, relevance scores, and transcript snippets.

### Parameters

| Parameter | Type    | Required | Description                             |
| --------- | ------- | -------- | --------------------------------------- |
| index\_id | string  | Yes      | ID of the index to search               |
| query     | string  | Yes      | Natural language search query           |
| limit     | integer | No       | Maximum number of results (default: 10) |

### Response

| Field   | Description             |
| ------- | ----------------------- |
| results | Array of matching clips |

### Result Object

| Field               | Description                                |
| ------------------- | ------------------------------------------ |
| clip\_url           | URL to the video clip                      |
| start\_time\_sec    | Start time of the clip in the source video |
| end\_time\_sec      | End time of the clip in the source video   |
| relevance\_score    | Relevance score from 0 to 1                |
| transcript\_snippet | Transcript excerpt from the clip           |

### Example Request

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/search/query \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "idx_abc123xyz",
    "query": "touchdown celebrations",
    "limit": 5
  }'
```

### Example Response

```json theme={null}
{
  "results": [
    {
      "clip_url": "https://cdn.usenarrative.ai/clips/clip_001.mp4",
      "start_time_sec": 145.5,
      "end_time_sec": 158.2,
      "relevance_score": 0.95,
      "transcript_snippet": "And he's in for the touchdown! What a play!"
    },
    {
      "clip_url": "https://cdn.usenarrative.ai/clips/clip_002.mp4",
      "start_time_sec": 892.1,
      "end_time_sec": 905.8,
      "relevance_score": 0.87,
      "transcript_snippet": "The team celebrates in the end zone..."
    }
  ]
}
```

### Notes

* Queries can be natural language (e.g., "moments where the crowd goes wild")
* Results are ranked by relevance score
* Each clip includes a transcript snippet for context
* Clip URLs are valid for 24 hours


## OpenAPI

````yaml POST /api/v1/search/query
openapi: 3.0.3
info:
  title: Search API
  description: Video clip indexing and natural language search API
  version: 1.0.0
servers:
  - url: https://api.usenarrative.ai
    description: Production
security: []
paths:
  /api/v1/search/query:
    post:
      tags:
        - Query
      summary: Search Clips
      description: >-
        Search for video clips using natural language queries. Returns relevant
        clips with timestamps and relevance scores.
      operationId: searchClips
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchClipsRequest'
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchClipsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Index not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchClipsRequest:
      type: object
      properties:
        index_id:
          type: string
          description: ID of the index to search
          example: idx_abc123xyz
        query:
          type: string
          description: Natural language search query
          example: touchdown celebrations
        limit:
          type: integer
          description: Maximum number of results to return
          default: 10
          example: 10
      required:
        - index_id
        - query
    SearchClipsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
          description: Array of matching clips
      required:
        - results
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
          example: Invalid request parameters
    SearchResult:
      type: object
      properties:
        clip_url:
          type: string
          format: uri
          description: URL to the video clip
          example: https://cdn.usenarrative.ai/clips/clip_abc123.mp4
        start_time_sec:
          type: number
          description: Start time of the clip in the source video
          example: 145.5
        end_time_sec:
          type: number
          description: End time of the clip in the source video
          example: 158.2
        relevance_score:
          type: number
          description: Relevance score from 0 to 1
          example: 0.92
        transcript_snippet:
          type: string
          description: Transcript excerpt from the clip
          example: And he's in for the touchdown! What a play!
      required:
        - clip_url
        - start_time_sec
        - end_time_sec
        - relevance_score

````