numpde/typesense-openapi.yml

## typesense-openapi.yml
openapi: 3.0.3
info:
  title: Typesense Notes API
  description: An API for creating and searching notes.
  version: 0.25.0
externalDocs:
  description: Find out more about Typesense
  url: https://typesense.org
servers:
  - url: https://************.a1.typesense.net
security:
  - api_key_header: []
tags:
  - name: notes
    description: Operations related to notes
    externalDocs:
      description: Find out more
      url: https://typesense.org/api/#index-document
paths:
  /collections/notes/documents:
    post:
      tags:
        - notes
      summary: Create a new note
      description: Adds a new note to the "notes" collection
      operationId: createNote
      requestBody:
        description: Note to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Note"
        required: true
      responses:
        "201":
          description: Note created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NoteCreationResponse"
        "400":
          description: Invalid input/Note schema incorrect
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - notes
      summary: Delete notes
      description: Delete notes that match a specific filter condition. Use the `batch_size` parameter to control the number
        of documents that should deleted at a time. Larger values speed up deletions, but impact performance.
      operationId: deleteNotes
      parameters:
        - name: filter_by
          in: query
          schema:
            type: string
            example: date:<2024-02-01
        - name: batch_size
          in: query
          description: Batch size for controlling deletion speed
          schema:
            type: integer
      responses:
        "200":
          description: Notes deleted successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - num_deleted
                properties:
                  num_deleted:
                    type: integer
        "400":
          description: Invalid parameters or filter syntax
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /collections/notes/documents/{documentId}:
    patch:
      tags:
        - notes
      summary: Update a note
      description: >
        Update an individual note from the "notes" collection by using its ID.
        The update can be partial.
      operationId: updateNote
      parameters:
        - name: documentId
          in: path
          description: The Note ID
          required: true
          schema:
            type: string
      requestBody:
        description: The note object with fields to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Note"
      responses:
        '200':
          description: The note referenced by the ID was updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Note"
        '404':
          description: The note or collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/notes/documents/search:
    get:
      tags:
        - notes
      summary: Search notes
      description: Search for notes that match the search criteria.
      operationId: searchNotes
      parameters:
        - in: query
          name: q
          required: true
          description: The query text to search for in the collection. Use * as the search string to return all documents. This is typically useful when used in conjunction with filter_by.
          schema:
            type: string
        - in: query
          name: query_by
          required: true
          description: A list of `string` fields that should be queried against. Multiple fields are separated with a comma.
          schema:
            type: string
        - in: query
          name: query_by_weights
          description: The relative weight to give each `query_by` field when ranking results. This can be used to boost fields in priority, when looking for matches. Multiple fields are separated with a comma.
          schema:
            type: string
        - in: query
          name: text_match_type
          description: In a multi-field matching context, this parameter determines how the representative text match score of a record is calculated. Possible values are max_score (default) or max_weight.
          schema:
            type: string
            default: max_score
        - in: query
          name: prefix
          description: Boolean field to indicate that the last word in the query should be treated as a prefix, and not as a whole word. This is used for building autocomplete and instant search interfaces. Defaults to true.
          schema:
            type: boolean
            default: true
        - in: query
          name: infix
          description: If infix index is enabled for this field, infix searching can be done on a per-field basis by sending a comma separated string parameter called infix to the search query. Values are `off`, `always`, `fallback`.
          schema:
            type: string
            default: off
        - in: query
          name: max_extra_prefix
          description: Maximum number of symbols before the query that can be present in the token. By default, any number of prefixes or suffixes can be present for a match.
          schema:
            type: integer
        - in: query
          name: max_extra_suffix
          description: Maximum number of symbols after the query that can be present in the token. By default, any number of prefixes or suffixes can be present for a match.
          schema:
            type: integer
        - in: query
          name: filter_by
          description: Filter conditions for refining your search results. Separate multiple conditions with &&.
          schema:
            type: string
            example: "num_employees:>100 && country: [USA, UK]"
        - in: query
          name: sort_by
          description: A list of numerical fields and their corresponding sort orders that will be used for ordering your results.
          schema:
            type: string
            example: num_employees:desc
        - in: query
          name: facet_by
          description: A list of fields that will be used for faceting your results on. Separate multiple fields with a comma.
          schema:
            type: string
        - in: query
          name: max_facet_values
          description: Maximum number of facet values to be returned.
          schema:
            type: integer
        - in: query
          name: facet_query
          description: Facet values that are returned can now be filtered via this parameter. The matching facet text is also highlighted. For example, when faceting by `category`, you can set `facet_query=category:shoe` to return only facet values that contain the prefix "shoe".
          schema:
            type: string
        - in: query
          name: num_typos
          description: |
            The number of typographical errors (1 or 2) that would be tolerated. Default: 2
          schema:
            type: string
        - in: query
          name: page
          description: Results from this specific page number would be fetched.
          schema:
            type: integer
        - in: query
          name: per_page
          description: "Number of results to fetch per page. Default: 10"
          schema:
            type: integer
        - in: query
          name: limit
          description: |
            Number of hits to fetch. Can be used as an alternative to the per_page parameter. Default: 10.
          schema:
            type: integer
        - in: query
          name: offset
          description: Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.
          schema:
            type: integer
        - in: query
          name: group_by
          description: You can aggregate search results into groups or buckets by specify one or more `group_by` fields. Separate multiple fields with a comma. To group on a particular field, it must be a faceted field.
          schema:
            type: string
        - in: query
          name: group_limit
          description: >
            Maximum number of hits to be returned for every group. If the `group_limit` is set as `K` then only the top K hits in each group are returned in the response. Default: 3
          schema:
            type: integer
        - in: query
          name: include_fields
          description: List of fields from the document to include in the search result
          schema:
            type: string
        - in: query
          name: exclude_fields
          description: List of fields from the document to exclude in the search result
          schema:
            type: string
        - in: query
          name: highlight_full_fields
          description: List of fields which should be highlighted fully without snippeting
          schema:
            type: string
        - in: query
          name: highlight_affix_num_tokens
          description: |
            The number of tokens that should surround the highlighted text on each side. Default: 4
          schema:
            type: integer
        - in: query
          name: highlight_start_tag
          description: |
            The start tag used for the highlighted snippets. Default: `<mark>`
          schema:
            type: string
        - in: query
          name: highlight_end_tag
          description: |
            The end tag used for the highlighted snippets. Default: `</mark>`
          schema:
            type: string
        - in: query
          name: enable_highlight_v1
          description: |
            Flag for enabling/disabling the deprecated, old highlight structure in the response. Default: true
          schema:
            type: boolean
            default: true
        - in: query
          name: snippet_threshold
          description: >
            Field values under this length will be fully highlighted, instead of showing a snippet of relevant portion. Default: 30
          schema:
            type: integer
        - in: query
          name: drop_tokens_threshold
          description: >
            If the number of results found for a specific query is less than this number, Typesense will attempt to drop the tokens in the query until enough results are found. Tokens that have the least individual hits are dropped first. Set to 0 to disable. Default: 10
          schema:
            type: integer
        - in: query
          name: typo_tokens_threshold
          description: >
            If the number of results found for a specific query is less than this number, Typesense will attempt to look for tokens with more typos until enough results are found. Default: 100
          schema:
            type: integer
        - in: query
          name: pinned_hits
          description: >
            A list of records to unconditionally include in the search results at specific positions. An example use case would be to feature or promote certain items on the top of search results. A list of `record_id:hit_position`. Eg: to include a record with ID 123 at Position 1 and another record with ID 456 at Position 5, you'd specify `123:1,456:5`.
            You could also use the Overrides feature to override search results based on rules. Overrides are applied first, followed by `pinned_hits` and finally `hidden_hits`.
          schema:
            type: string
        - in: query
          name: hidden_hits
          description: >
            A list of records to unconditionally hide from search results. A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456, you'd specify `123,456`.

            You could also use the Overrides feature to override search results based on rules. Overrides are applied first, followed by `pinned_hits` and finally `hidden_hits`.
          schema:
            type: string
        - in: query
          name: highlight_fields
          description: |
            A list of custom fields that must be highlighted even if you don't query for them
          schema:
            type: string
        - in: query
          name: split_join_tokens
          description: >
            Treat space as typo: search for q=basket ball if q=basketball is not found or vice-versa. Splitting/joining of tokens will only be attempted if the original query produces no results. To always trigger this behavior, set value to `always``. To disable, set value to `off`. Default is `fallback`.
          schema:
            type: string
        - in: query
          name: pre_segmented_query
          description: >
            You can index content from any logographic language into Typesense if you are able to segment / split the text into space-separated words yourself before indexing and querying. Set this parameter to true to do the same
          schema:
            type: boolean
        - in: query
          name: preset
          description: |
            Search using a bunch of search parameters by setting this parameter to the name of the existing Preset.
          schema:
            type: string
        - in: query
          name: enable_overrides
          description: >
            If you have some overrides defined but want to disable all of them during query time, you can do that by setting this parameter to false
          schema:
            type: boolean
        - in: query
          name: prioritize_exact_match
          description: |
            Set this parameter to true to ensure that an exact match is ranked above the others
          schema:
            type: boolean
        - in: query
          name: max_candidates
          description: |
            Control the number of words that Typesense considers for typo and prefix searching.
          schema:
            type: integer
        - in: query
          name: prioritize_token_position
          description: |
            Make Typesense prioritize documents where the query words appear earlier in the text.
          schema:
            type: boolean
        - in: query
          name: exhaustive_search
          description: >
            Setting this to true will make Typesense consider all prefixes and typo corrections of the words in the query without stopping early when enough results are found (drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
          schema:
            type: boolean
        - in: query
          name: search_cutoff_ms
          description: >
            Typesense will attempt to return results early if the cutoff time has elapsed. This is not a strict guarantee and facet computation is not bound by this parameter.
          schema:
            type: integer
        - in: query
          name: use_cache
          description: |
            Enable server side caching of search query results. By default, caching is disabled.
          schema:
            type: boolean
        - in: query
          name: cache_ttl
          description: >
            The duration (in seconds) that determines how long the search query is cached. This value can be set on a per-query basis. Default: 60.
          schema:
            type: integer
        - in: query
          name: min_len_1typo
          description: >
            Minimum word length for 1-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.
          schema:
            type: integer
        - in: query
          name: min_len_2typo
          description: >
            Minimum word length for 2-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.
          schema:
            type: integer
        - in: query
          name: vector_query
          description: |
            Vector query expression for fetching documents "closest" to a given query/document vector.
          schema:
            type: string
        - in: query
          name: remote_embedding_timeout_ms
          description: |
            Timeout (in milliseconds) for fetching remote embeddings.
          schema:
            type: integer
        - in: query
          name: remote_embedding_num_tries
          description: |
            Number of times to retry fetching remote embeddings.
          schema:
            type: integer
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /debug:
    get:
      tags:
        - debug
      summary: Print debugging information
      description: Print debugging information
      operationId: debug
      responses:
        "200":
          description: Debugging information
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
  /health:
    get:
      tags:
        - health
      summary: Checks if Typesense server is ready to accept requests.
      description: Checks if Typesense server is ready to accept requests.
      operationId: health
      responses:
        "200":
          description: Search service is ready for requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

components:
  schemas:
    Note:
      type: object
      properties:
        summary:
          type: string
          description: A brief summary of the note.
        note:
          type: string
          description: The detailed content of the note.
        date:
          type: string
          format: date
          description: The date the note was created or modified (YYYY-MM-DD).
        tags:
          type: array
          items:
            type: string
          description: A list of tags associated with the note.
        from:
          type: string
          description: The sender or originator of the note.
      required:
        - summary
        - note
        - date
        - from

    NoteCreationResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the newly created note.
        summary:
          type: string
          description: The summary of the created note.
        note:
          type: string
          description: The full content of the created note.
        date:
          type: string
          format: date
          description: The date and time the note was created or modified (YYYY-MM-DD).
        tags:
          type: array
          items:
            type: string
          description: A list of tags associated with the note.
        from:
          type: string
          description: The sender or originator of the note.

    SearchResult:
      type: object
      properties:
        facet_counts:
          type: array
          items:
            $ref: "#/components/schemas/FacetCounts"
        found:
          type: integer
          description: The number of documents found
        search_time_ms:
          type: integer
          description: The number of milliseconds the search took
        out_of:
          type: integer
          description: The total number of documents in the collection
        search_cutoff:
          type: boolean
          description: Whether the search was cut off
        page:
          type: integer
          description: The search result page number
        grouped_hits:
          type: array
          items:
            $ref: "#/components/schemas/SearchGroupedHit"
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
        request_params:
          type: object
          required:
            - collection_name
            - q
            - per_page
          properties:
            collection_name:
              type: string
            q:
              type: string
            per_page:
              type: integer
    SearchGroupedHit:
      type: object
      required:
        - group_key
        - hits
      properties:
        found:
          type: integer
        group_key:
          type: array
          items: {}
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
    SearchResultHit:
      type: object
      properties:
        highlights:
          type: array
          description: (Deprecated) Contains highlighted portions of the search fields
          items:
            $ref: "#/components/schemas/SearchHighlight"
        highlight:
          type: object
          description: Highlighted version of the matching document
          additionalProperties: true
        document:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: object
        text_match:
          type: integer
          format: int64
        geo_distance_meters:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: integer
        vector_distance:
          type: number
          format: float
          description: Distance between the query vector and matching document's vector value
      example:
        highlights:
          company_name:
            field: company_name
            snippet: <mark>Stark</mark> Industries
        document:
          id: "124"
          company_name: Stark Industries
          num_employees: 5215
          country: USA
        text_match: 1234556
    SearchHighlight:
      type: object
      properties:
        field:
          type: string
          example: company_name
        snippet:
          type: string
          description: Present only for (non-array) string fields
          example: <mark>Stark</mark> Industries
        snippets:
          type: array
          description: Present only for (array) string[] fields
          example:
            - <mark>Stark</mark> Industries
            - <mark>Stark</mark> Corp
          items:
            type: string
        value:
          type: string
          description: Full field value with highlighting, present only for (non-array) string fields
          example: <mark>Stark</mark> Industries is a major supplier of space equipment.
        values:
          type: array
          description: Full field value with highlighting, present only for (array) string[] fields
          example:
            - <mark>Stark</mark> Industries
            - <mark>Stark</mark> Corp
          items:
            type: string
        indices:
          type: array
          description: The indices property will be present only for string[] fields and will contain the corresponding indices of
            the snippets in the search field
          example: 1
          items:
            type: integer
        matched_tokens:
          type: array
          items:
            type: object
            x-go-type: interface{}
    HealthStatus:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
    SuccessStatus:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
    ApiResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    FacetCounts:
      type: object
      properties:
        counts:
          type: array
          items:
            type: object
            properties:
              count:
                type: integer
              highlighted:
                type: string
              value:
                type: string
        field_name:
          type: string
        stats:
          type: object
          properties:
            max:
              type: number
              format: double
            min:
              type: number
              format: double
            sum:
              type: number
              format: double
            total_values:
              type: integer
            avg:
              type: number
              format: double
  securitySchemes:
    api_key_header:
      type: apiKey
      name: X-TYPESENSE-API-KEY
      in: header
	openapi: 3.0.3
	info:
	title: Typesense Notes API
	description: An API for creating and searching notes.
	version: 0.25.0
	externalDocs:
	description: Find out more about Typesense
	url: https://typesense.org
	servers:
	- url: https://************.a1.typesense.net
	security:
	- api_key_header: []
	tags:
	- name: notes
	description: Operations related to notes
	externalDocs:
	description: Find out more
	url: https://typesense.org/api/#index-document
	paths:
	/collections/notes/documents:
	post:
	tags:
	- notes
	summary: Create a new note
	description: Adds a new note to the "notes" collection
	operationId: createNote
	requestBody:
	description: Note to be created
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/Note"
	required: true
	responses:
	"201":
	description: Note created successfully
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/NoteCreationResponse"
	"400":
	description: Invalid input/Note schema incorrect
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/ErrorResponse"
	delete:
	tags:
	- notes
	summary: Delete notes
	description: Delete notes that match a specific filter condition. Use the `batch_size` parameter to control the number
	of documents that should deleted at a time. Larger values speed up deletions, but impact performance.
	operationId: deleteNotes
	parameters:
	- name: filter_by
	in: query
	schema:
	type: string
	example: date:<2024-02-01
	- name: batch_size
	in: query
	description: Batch size for controlling deletion speed
	schema:
	type: integer
	responses:
	"200":
	description: Notes deleted successfully
	content:
	application/json:
	schema:
	type: object
	required:
	- num_deleted
	properties:
	num_deleted:
	type: integer
	"400":
	description: Invalid parameters or filter syntax
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/ErrorResponse"
	/collections/notes/documents/{documentId}:
	patch:
	tags:
	- notes
	summary: Update a note
	description: >
	Update an individual note from the "notes" collection by using its ID.
	The update can be partial.
	operationId: updateNote
	parameters:
	- name: documentId
	in: path
	description: The Note ID
	required: true
	schema:
	type: string
	requestBody:
	description: The note object with fields to be updated
	required: true
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/Note"
	responses:
	'200':
	description: The note referenced by the ID was updated
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/Note"
	'404':
	description: The note or collection was not found
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/ApiResponse"
	/collections/notes/documents/search:
	get:
	tags:
	- notes
	summary: Search notes
	description: Search for notes that match the search criteria.
	operationId: searchNotes
	parameters:
	- in: query
	name: q
	required: true
	description: The query text to search for in the collection. Use * as the search string to return all documents. This is typically useful when used in conjunction with filter_by.
	schema:
	type: string
	- in: query
	name: query_by
	required: true
	description: A list of `string` fields that should be queried against. Multiple fields are separated with a comma.
	schema:
	type: string
	- in: query
	name: query_by_weights
	description: The relative weight to give each `query_by` field when ranking results. This can be used to boost fields in priority, when looking for matches. Multiple fields are separated with a comma.
	schema:
	type: string
	- in: query
	name: text_match_type
	description: In a multi-field matching context, this parameter determines how the representative text match score of a record is calculated. Possible values are max_score (default) or max_weight.
	schema:
	type: string
	default: max_score
	- in: query
	name: prefix
	description: Boolean field to indicate that the last word in the query should be treated as a prefix, and not as a whole word. This is used for building autocomplete and instant search interfaces. Defaults to true.
	schema:
	type: boolean
	default: true
	- in: query
	name: infix
	description: If infix index is enabled for this field, infix searching can be done on a per-field basis by sending a comma separated string parameter called infix to the search query. Values are `off`, `always`, `fallback`.
	schema:
	type: string
	default: off
	- in: query
	name: max_extra_prefix
	description: Maximum number of symbols before the query that can be present in the token. By default, any number of prefixes or suffixes can be present for a match.
	schema:
	type: integer
	- in: query
	name: max_extra_suffix
	description: Maximum number of symbols after the query that can be present in the token. By default, any number of prefixes or suffixes can be present for a match.
	schema:
	type: integer
	- in: query
	name: filter_by
	description: Filter conditions for refining your search results. Separate multiple conditions with &&.
	schema:
	type: string
	example: "num_employees:>100 && country: [USA, UK]"
	- in: query
	name: sort_by
	description: A list of numerical fields and their corresponding sort orders that will be used for ordering your results.
	schema:
	type: string
	example: num_employees:desc
	- in: query
	name: facet_by
	description: A list of fields that will be used for faceting your results on. Separate multiple fields with a comma.
	schema:
	type: string
	- in: query
	name: max_facet_values
	description: Maximum number of facet values to be returned.
	schema:
	type: integer
	- in: query
	name: facet_query
	description: Facet values that are returned can now be filtered via this parameter. The matching facet text is also highlighted. For example, when faceting by `category`, you can set `facet_query=category:shoe` to return only facet values that contain the prefix "shoe".
	schema:
	type: string
	- in: query
	name: num_typos
	description: \|
	The number of typographical errors (1 or 2) that would be tolerated. Default: 2
	schema:
	type: string
	- in: query
	name: page
	description: Results from this specific page number would be fetched.
	schema:
	type: integer
	- in: query
	name: per_page
	description: "Number of results to fetch per page. Default: 10"
	schema:
	type: integer
	- in: query
	name: limit
	description: \|
	Number of hits to fetch. Can be used as an alternative to the per_page parameter. Default: 10.
	schema:
	type: integer
	- in: query
	name: offset
	description: Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.
	schema:
	type: integer
	- in: query
	name: group_by
	description: You can aggregate search results into groups or buckets by specify one or more `group_by` fields. Separate multiple fields with a comma. To group on a particular field, it must be a faceted field.
	schema:
	type: string
	- in: query
	name: group_limit
	description: >
	Maximum number of hits to be returned for every group. If the `group_limit` is set as `K` then only the top K hits in each group are returned in the response. Default: 3
	schema:
	type: integer
	- in: query
	name: include_fields
	description: List of fields from the document to include in the search result
	schema:
	type: string
	- in: query
	name: exclude_fields
	description: List of fields from the document to exclude in the search result
	schema:
	type: string
	- in: query
	name: highlight_full_fields
	description: List of fields which should be highlighted fully without snippeting
	schema:
	type: string
	- in: query
	name: highlight_affix_num_tokens
	description: \|
	The number of tokens that should surround the highlighted text on each side. Default: 4
	schema:
	type: integer
	- in: query
	name: highlight_start_tag
	description: \|
	The start tag used for the highlighted snippets. Default: `<mark>`
	schema:
	type: string
	- in: query
	name: highlight_end_tag
	description: \|
	The end tag used for the highlighted snippets. Default: `</mark>`
	schema:
	type: string
	- in: query
	name: enable_highlight_v1
	description: \|
	Flag for enabling/disabling the deprecated, old highlight structure in the response. Default: true
	schema:
	type: boolean
	default: true
	- in: query
	name: snippet_threshold
	description: >
	Field values under this length will be fully highlighted, instead of showing a snippet of relevant portion. Default: 30
	schema:
	type: integer
	- in: query
	name: drop_tokens_threshold
	description: >
	If the number of results found for a specific query is less than this number, Typesense will attempt to drop the tokens in the query until enough results are found. Tokens that have the least individual hits are dropped first. Set to 0 to disable. Default: 10
	schema:
	type: integer
	- in: query
	name: typo_tokens_threshold
	description: >
	If the number of results found for a specific query is less than this number, Typesense will attempt to look for tokens with more typos until enough results are found. Default: 100
	schema:
	type: integer
	- in: query
	name: pinned_hits
	description: >
	A list of records to unconditionally include in the search results at specific positions. An example use case would be to feature or promote certain items on the top of search results. A list of `record_id:hit_position`. Eg: to include a record with ID 123 at Position 1 and another record with ID 456 at Position 5, you'd specify `123:1,456:5`.
	You could also use the Overrides feature to override search results based on rules. Overrides are applied first, followed by `pinned_hits` and finally `hidden_hits`.
	schema:
	type: string
	- in: query
	name: hidden_hits
	description: >
	A list of records to unconditionally hide from search results. A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456, you'd specify `123,456`.

	You could also use the Overrides feature to override search results based on rules. Overrides are applied first, followed by `pinned_hits` and finally `hidden_hits`.
	schema:
	type: string
	- in: query
	name: highlight_fields
	description: \|
	A list of custom fields that must be highlighted even if you don't query for them
	schema:
	type: string
	- in: query
	name: split_join_tokens
	description: >
	Treat space as typo: search for q=basket ball if q=basketball is not found or vice-versa. Splitting/joining of tokens will only be attempted if the original query produces no results. To always trigger this behavior, set value to `always``. To disable, set value to `off`. Default is `fallback`.
	schema:
	type: string
	- in: query
	name: pre_segmented_query
	description: >
	You can index content from any logographic language into Typesense if you are able to segment / split the text into space-separated words yourself before indexing and querying. Set this parameter to true to do the same
	schema:
	type: boolean
	- in: query
	name: preset
	description: \|
	Search using a bunch of search parameters by setting this parameter to the name of the existing Preset.
	schema:
	type: string
	- in: query
	name: enable_overrides
	description: >
	If you have some overrides defined but want to disable all of them during query time, you can do that by setting this parameter to false
	schema:
	type: boolean
	- in: query
	name: prioritize_exact_match
	description: \|
	Set this parameter to true to ensure that an exact match is ranked above the others
	schema:
	type: boolean
	- in: query
	name: max_candidates
	description: \|
	Control the number of words that Typesense considers for typo and prefix searching.
	schema:
	type: integer
	- in: query
	name: prioritize_token_position
	description: \|
	Make Typesense prioritize documents where the query words appear earlier in the text.
	schema:
	type: boolean
	- in: query
	name: exhaustive_search
	description: >
	Setting this to true will make Typesense consider all prefixes and typo corrections of the words in the query without stopping early when enough results are found (drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
	schema:
	type: boolean
	- in: query
	name: search_cutoff_ms
	description: >
	Typesense will attempt to return results early if the cutoff time has elapsed. This is not a strict guarantee and facet computation is not bound by this parameter.
	schema:
	type: integer
	- in: query
	name: use_cache
	description: \|
	Enable server side caching of search query results. By default, caching is disabled.
	schema:
	type: boolean
	- in: query
	name: cache_ttl
	description: >
	The duration (in seconds) that determines how long the search query is cached. This value can be set on a per-query basis. Default: 60.
	schema:
	type: integer
	- in: query
	name: min_len_1typo
	description: >
	Minimum word length for 1-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.
	schema:
	type: integer
	- in: query
	name: min_len_2typo
	description: >
	Minimum word length for 2-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.
	schema:
	type: integer
	- in: query
	name: vector_query
	description: \|
	Vector query expression for fetching documents "closest" to a given query/document vector.
	schema:
	type: string
	- in: query
	name: remote_embedding_timeout_ms
	description: \|
	Timeout (in milliseconds) for fetching remote embeddings.
	schema:
	type: integer
	- in: query
	name: remote_embedding_num_tries
	description: \|
	Number of times to retry fetching remote embeddings.
	schema:
	type: integer
	responses:
	"200":
	description: Search results
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/SearchResult"
	"400":
	description: Bad request
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/ErrorResponse"
	/debug:
	get:
	tags:
	- debug
	summary: Print debugging information
	description: Print debugging information
	operationId: debug
	responses:
	"200":
	description: Debugging information
	content:
	application/json:
	schema:
	type: object
	properties:
	version:
	type: string
	/health:
	get:
	tags:
	- health
	summary: Checks if Typesense server is ready to accept requests.
	description: Checks if Typesense server is ready to accept requests.
	operationId: health
	responses:
	"200":
	description: Search service is ready for requests.
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/HealthStatus"

	components:
	schemas:
	Note:
	type: object
	properties:
	summary:
	type: string
	description: A brief summary of the note.
	note:
	type: string
	description: The detailed content of the note.
	date:
	type: string
	format: date
	description: The date the note was created or modified (YYYY-MM-DD).
	tags:
	type: array
	items:
	type: string
	description: A list of tags associated with the note.
	from:
	type: string
	description: The sender or originator of the note.
	required:
	- summary
	- note
	- date
	- from

	NoteCreationResponse:
	type: object
	properties:
	id:
	type: string
	description: The unique identifier of the newly created note.
	summary:
	type: string
	description: The summary of the created note.
	note:
	type: string
	description: The full content of the created note.
	date:
	type: string
	format: date
	description: The date and time the note was created or modified (YYYY-MM-DD).
	tags:
	type: array
	items:
	type: string
	description: A list of tags associated with the note.
	from:
	type: string
	description: The sender or originator of the note.

	SearchResult:
	type: object
	properties:
	facet_counts:
	type: array
	items:
	$ref: "#/components/schemas/FacetCounts"
	found:
	type: integer
	description: The number of documents found
	search_time_ms:
	type: integer
	description: The number of milliseconds the search took
	out_of:
	type: integer
	description: The total number of documents in the collection
	search_cutoff:
	type: boolean
	description: Whether the search was cut off
	page:
	type: integer
	description: The search result page number
	grouped_hits:
	type: array
	items:
	$ref: "#/components/schemas/SearchGroupedHit"
	hits:
	type: array
	description: The documents that matched the search query
	items:
	$ref: "#/components/schemas/SearchResultHit"
	request_params:
	type: object
	required:
	- collection_name
	- q
	- per_page
	properties:
	collection_name:
	type: string
	q:
	type: string
	per_page:
	type: integer
	SearchGroupedHit:
	type: object
	required:
	- group_key
	- hits
	properties:
	found:
	type: integer
	group_key:
	type: array
	items: {}
	hits:
	type: array
	description: The documents that matched the search query
	items:
	$ref: "#/components/schemas/SearchResultHit"
	SearchResultHit:
	type: object
	properties:
	highlights:
	type: array
	description: (Deprecated) Contains highlighted portions of the search fields
	items:
	$ref: "#/components/schemas/SearchHighlight"
	highlight:
	type: object
	description: Highlighted version of the matching document
	additionalProperties: true
	document:
	type: object
	description: Can be any key-value pair
	additionalProperties:
	type: object
	text_match:
	type: integer
	format: int64
	geo_distance_meters:
	type: object
	description: Can be any key-value pair
	additionalProperties:
	type: integer
	vector_distance:
	type: number
	format: float
	description: Distance between the query vector and matching document's vector value
	example:
	highlights:
	company_name:
	field: company_name
	snippet: <mark>Stark</mark> Industries
	document:
	id: "124"
	company_name: Stark Industries
	num_employees: 5215
	country: USA
	text_match: 1234556
	SearchHighlight:
	type: object
	properties:
	field:
	type: string
	example: company_name
	snippet:
	type: string
	description: Present only for (non-array) string fields
	example: <mark>Stark</mark> Industries
	snippets:
	type: array
	description: Present only for (array) string[] fields
	example:
	- <mark>Stark</mark> Industries
	- <mark>Stark</mark> Corp
	items:
	type: string
	value:
	type: string
	description: Full field value with highlighting, present only for (non-array) string fields
	example: <mark>Stark</mark> Industries is a major supplier of space equipment.
	values:
	type: array
	description: Full field value with highlighting, present only for (array) string[] fields
	example:
	- <mark>Stark</mark> Industries
	- <mark>Stark</mark> Corp
	items:
	type: string
	indices:
	type: array
	description: The indices property will be present only for string[] fields and will contain the corresponding indices of
	the snippets in the search field
	example: 1
	items:
	type: integer
	matched_tokens:
	type: array
	items:
	type: object
	x-go-type: interface{}
	HealthStatus:
	type: object
	required:
	- ok
	properties:
	ok:
	type: boolean
	SuccessStatus:
	type: object
	required:
	- success
	properties:
	success:
	type: boolean
	ApiResponse:
	type: object
	required:
	- message
	properties:
	message:
	type: string
	ErrorResponse:
	type: object
	properties:
	message:
	type: string
	FacetCounts:
	type: object
	properties:
	counts:
	type: array
	items:
	type: object
	properties:
	count:
	type: integer
	highlighted:
	type: string
	value:
	type: string
	field_name:
	type: string
	stats:
	type: object
	properties:
	max:
	type: number
	format: double
	min:
	type: number
	format: double
	sum:
	type: number
	format: double
	total_values:
	type: integer
	avg:
	type: number
	format: double
	securitySchemes:
	api_key_header:
	type: apiKey
	name: X-TYPESENSE-API-KEY
	in: header