{
  "paths": {
    "/{space_id}/clip_search": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "terms",
            "description": "Free-text user query to search for.",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "qid",
            "description": "Optional content id to restrict the search to.",
            "schema": {
              "type": "string",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "start",
            "description": "Pagination offset into the matched clips.",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "required": false
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Maximum number of clips to return.",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "required": false
          },
          {
            "in": "query",
            "name": "debug",
            "description": "Include debug payload.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "required": false
          },
          {
            "in": "query",
            "name": "clips_min_duration",
            "description": "Minimum clip duration in seconds (else server default).",
            "schema": {
              "type": "number",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "clips_max_duration",
            "description": "Maximum clip duration in seconds (else server default).",
            "schema": {
              "type": "number",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "rerank_user_query",
            "description": "Advanced search configuration option: if true, the user's original query is embedded for the semantic vector search instead of the decomposed semantic component. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "rerank_level",
            "description": "Advanced search configuration option: the amount of context to provide to the reranker: can be 'chunk', 'tag', or 'document' (increasing levels of context). Defaults to 'tag' level.",
            "schema": {
              "type": "string",
              "default": null,
              "nullable": true
            },
            "required": false
          }
        ],
        "responses": {
          "422": {
            "$ref": "#/components/responses/UNPROCESSABLE_ENTITY"
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClipSearchResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/DEFAULT_ERROR"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClipSearchBody"
              }
            }
          }
        },
        "tags": [
          "content_search"
        ]
      },
      "post": {
        "parameters": [
          {
            "in": "query",
            "name": "terms",
            "description": "Free-text user query to search for.",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "qid",
            "description": "Optional content id to restrict the search to.",
            "schema": {
              "type": "string",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "start",
            "description": "Pagination offset into the matched clips.",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "required": false
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Maximum number of clips to return.",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "required": false
          },
          {
            "in": "query",
            "name": "debug",
            "description": "Include debug payload.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "required": false
          },
          {
            "in": "query",
            "name": "clips_min_duration",
            "description": "Minimum clip duration in seconds (else server default).",
            "schema": {
              "type": "number",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "clips_max_duration",
            "description": "Maximum clip duration in seconds (else server default).",
            "schema": {
              "type": "number",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "rerank_user_query",
            "description": "Advanced search configuration option: if true, the user's original query is embedded for the semantic vector search instead of the decomposed semantic component. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": null,
              "nullable": true
            },
            "required": false
          },
          {
            "in": "query",
            "name": "rerank_level",
            "description": "Advanced search configuration option: the amount of context to provide to the reranker: can be 'chunk', 'tag', or 'document' (increasing levels of context). Defaults to 'tag' level.",
            "schema": {
              "type": "string",
              "default": null,
              "nullable": true
            },
            "required": false
          }
        ],
        "responses": {
          "422": {
            "$ref": "#/components/responses/UNPROCESSABLE_ENTITY"
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClipSearchResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/DEFAULT_ERROR"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClipSearchBody"
              }
            }
          }
        },
        "tags": [
          "content_search"
        ]
      },
      "parameters": [
        {
          "in": "path",
          "name": "space_id",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ]
    },
    "/{space_id}/tracks": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "authorization",
            "description": "Optional authorization token (else use the header).",
            "schema": {
              "type": "string",
              "default": null,
              "nullable": true
            },
            "required": false
          }
        ],
        "responses": {
          "422": {
            "$ref": "#/components/responses/UNPROCESSABLE_ENTITY"
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TracksResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/DEFAULT_ERROR"
          }
        },
        "tags": [
          "content_search"
        ]
      },
      "parameters": [
        {
          "in": "path",
          "name": "space_id",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ]
    }
  },
  "info": {
    "title": "Content Search API",
    "version": "v1"
  },
  "tags": [
    {
      "name": "content_search",
      "description": "Clip search over the vector store."
    }
  ],
  "openapi": "3.0.2",
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error code"
          },
          "status": {
            "type": "string",
            "description": "Error name"
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "errors": {
            "type": "object",
            "description": "Errors",
            "additionalProperties": {}
          }
        },
        "additionalProperties": false
      },
      "PaginationMetadata": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items."
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages."
          },
          "first_page": {
            "type": "integer",
            "description": "First available page number."
          },
          "last_page": {
            "type": "integer",
            "description": "Last available page number."
          },
          "page": {
            "type": "integer",
            "description": "Current page number."
          },
          "previous_page": {
            "type": "integer",
            "description": "Previous page number."
          },
          "next_page": {
            "type": "integer",
            "description": "Next page number."
          }
        },
        "additionalProperties": false
      },
      "TextFilter": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "websearch_to_tsquery phrase."
          },
          "target": {
            "type": "string",
            "default": null,
            "description": "'document' (default) or 'tag'.",
            "nullable": true
          },
          "track": {
            "type": "string",
            "default": null,
            "description": "Tag track; only valid when target == 'tag'.",
            "nullable": true
          }
        },
        "required": [
          "query"
        ]
      },
      "ClipSearchBody": {
        "type": "object",
        "properties": {
          "text_filters": {
            "type": "array",
            "description": "Filters appended verbatim to the semantic search.",
            "items": {
              "$ref": "#/components/schemas/TextFilter"
            }
          }
        }
      },
      "Clip": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Title of the associated content document, or the qid if absent."
          },
          "document_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "start": {
            "type": "string",
            "description": "Human-readable start, e.g. '2m22.01s'."
          },
          "end": {
            "type": "string",
            "description": "Human-readable end, e.g. '3m4.833s'."
          },
          "start_time": {
            "type": "integer",
            "description": "Clip start in milliseconds."
          },
          "end_time": {
            "type": "integer",
            "description": "Clip end in milliseconds."
          },
          "score": {
            "type": "number"
          },
          "image_url": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "document_ids",
          "end",
          "end_time",
          "id",
          "image_url",
          "name",
          "score",
          "start",
          "start_time",
          "url"
        ],
        "additionalProperties": false
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "start": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "total_clips": {
            "type": "integer"
          }
        },
        "required": [
          "count",
          "limit",
          "start",
          "total_clips"
        ],
        "additionalProperties": false
      },
      "MatchInfo": {
        "type": "object",
        "properties": {
          "chunk": {
            "type": "string"
          },
          "chunk_relevance": {
            "type": "number"
          },
          "rerank_relevance": {
            "type": "number"
          },
          "rerank_text": {
            "type": "string",
            "description": "The exact text the reranker scored on (the chunk, tag, or containing-document text, per rerank_level). rerank_relevance is its reranker score."
          }
        },
        "required": [
          "chunk",
          "chunk_relevance",
          "rerank_relevance",
          "rerank_text"
        ],
        "additionalProperties": false
      },
      "MatchedDocument": {
        "type": "object",
        "properties": {
          "document_id": {
            "type": "string",
            "nullable": true
          },
          "match_info": {
            "$ref": "#/components/schemas/MatchInfo"
          }
        },
        "required": [
          "match_info"
        ],
        "additionalProperties": false
      },
      "DebugInfo": {
        "type": "object",
        "properties": {
          "semantic_query": {
            "type": "string"
          },
          "filter_query": {
            "type": "string",
            "nullable": true
          },
          "rerank_query": {
            "type": "string",
            "nullable": true
          },
          "matched_documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatchedDocument"
            },
            "nullable": true
          }
        },
        "required": [
          "semantic_query"
        ],
        "additionalProperties": false
      },
      "ClipSearchResponse": {
        "type": "object",
        "properties": {
          "contents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Clip"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "debug": {
            "$ref": "#/components/schemas/DebugInfo"
          }
        },
        "required": [
          "contents",
          "pagination"
        ],
        "additionalProperties": false
      },
      "ResolvedTrack": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Unique track name."
          },
          "label": {
            "type": "string",
            "description": "Human-readable display label."
          }
        },
        "required": [
          "label",
          "name"
        ],
        "additionalProperties": false
      },
      "TracksResponse": {
        "type": "object",
        "properties": {
          "tracks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResolvedTrack"
            }
          }
        },
        "required": [
          "tracks"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "UNPROCESSABLE_ENTITY": {
        "description": "Unprocessable Entity",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "DEFAULT_ERROR": {
        "description": "Default error response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}