@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Typesense API
@base http://localhost:8108
@version 30.0
@auth ApiKey X-TYPESENSE-API-KEY in header
@endpoints 79
@hint download_for_search
@toc collections(14), synonym_sets(8), curation_sets(8), conversations(5), keys(4), aliases(4), debug(1), health(1), operations(5), config(1), multi_search(1), analytics(9), metrics.json(1), stats.json(1), stopwords(4), presets(4), stemming(3), nl_search_models(5)

@group collections
@endpoint GET /collections
@optional {getCollectionsParameters: map}
@returns(200)

@endpoint POST /collections
@required {name: str, fields: [map{name!: str, type!: str, optional: bool, facet: bool, index: bool, locale: str, sort: bool, infix: bool, reference: str, async_reference: bool, num_dim: int, drop: bool, store: bool, vec_dist: str, range_index: bool, stem: bool, stem_dictionary: str, token_separators: [str], symbols_to_index: [str], embed: map}]}
@optional {default_sorting_field: str=, token_separators: [str]=, synonym_sets: [str], enable_nested_fields: bool=false, symbols_to_index: [str]=, voice_query_model: map{model_name: str}, metadata: map}
@returns(201)
@errors {400, 409}

@endpoint GET /collections/{collectionName}
@required {collectionName: str}
@returns(200)
@errors {404}

@endpoint PATCH /collections/{collectionName}
@required {collectionName: str, fields: [map{name!: str, type!: str, optional: bool, facet: bool, index: bool, locale: str, sort: bool, infix: bool, reference: str, async_reference: bool, num_dim: int, drop: bool, store: bool, vec_dist: str, range_index: bool, stem: bool, stem_dictionary: str, token_separators: [str], symbols_to_index: [str], embed: map}]}
@optional {synonym_sets: [str], metadata: map}
@returns(200) {fields: [map], synonym_sets: [str], metadata: map}
@errors {400, 404}

@endpoint DELETE /collections/{collectionName}
@required {collectionName: str}
@returns(200)
@errors {404}

@endpoint POST /collections/{collectionName}/documents
@required {collectionName: str}
@optional {action: str, dirty_values: str}
@returns(201)
@errors {404}

@endpoint PATCH /collections/{collectionName}/documents
@required {collectionName: str}
@optional {updateDocumentsParameters: map}
@returns(200) {num_updated: int}
@errors {400, 404}

@endpoint DELETE /collections/{collectionName}/documents
@required {collectionName: str}
@optional {deleteDocumentsParameters: map}
@returns(200) {num_deleted: int}
@errors {404}

@endpoint GET /collections/{collectionName}/documents/search
@required {collectionName: str, searchParameters: map}
@returns(200) {facet_counts: [map], found: int, found_docs: int, search_time_ms: int, out_of: int, search_cutoff: bool, page: int, grouped_hits: [map], hits: [map], request_params: map{collection_name: str, first_q: str, q: str, per_page: int, voice_query: map{transcribed_query: str}}, conversation: map{answer: str, conversation_history: [map], conversation_id: str, query: str}, union_request_params: [map], metadata: map}
@errors {400, 404}

@endgroup

@group synonym_sets
@endpoint GET /synonym_sets
@returns(200)

@endpoint GET /synonym_sets/{synonymSetName}
@required {synonymSetName: str}
@returns(200)
@errors {404}

@endpoint PUT /synonym_sets/{synonymSetName}
@required {synonymSetName: str, items: [any]}
@returns(200)
@errors {400}

@endpoint DELETE /synonym_sets/{synonymSetName}
@required {synonymSetName: str}
@returns(200) {name: str}
@errors {404}

@endpoint GET /synonym_sets/{synonymSetName}/items
@required {synonymSetName: str}
@returns(200)
@errors {404}

@endpoint GET /synonym_sets/{synonymSetName}/items/{itemId}
@required {synonymSetName: str, itemId: str}
@returns(200)
@errors {404}

@endpoint PUT /synonym_sets/{synonymSetName}/items/{itemId}
@required {synonymSetName: str, itemId: str, synonyms: [str]}
@optional {root: str, locale: str, symbols_to_index: [str]}
@returns(200)
@errors {400}

@endpoint DELETE /synonym_sets/{synonymSetName}/items/{itemId}
@required {synonymSetName: str, itemId: str}
@returns(200) {id: str}
@errors {404}

@endgroup

@group curation_sets
@endpoint GET /curation_sets
@returns(200)

@endpoint GET /curation_sets/{curationSetName}
@required {curationSetName: str}
@returns(200)
@errors {404}

@endpoint PUT /curation_sets/{curationSetName}
@required {curationSetName: str, items: [map{rule!: map, includes: [map], excludes: [map], filter_by: str, remove_matched_tokens: bool, metadata: map, sort_by: str, replace_query: str, filter_curated_hits: bool, effective_from_ts: int, effective_to_ts: int, stop_processing: bool, id: str}]}
@optional {description: str}
@returns(200)
@errors {400}

@endpoint DELETE /curation_sets/{curationSetName}
@required {curationSetName: str}
@returns(200) {name: str}
@errors {404}

@endpoint GET /curation_sets/{curationSetName}/items
@required {curationSetName: str}
@returns(200)
@errors {404}

@endpoint GET /curation_sets/{curationSetName}/items/{itemId}
@required {curationSetName: str, itemId: str}
@returns(200)
@errors {404}

@endpoint PUT /curation_sets/{curationSetName}/items/{itemId}
@required {curationSetName: str, itemId: str, rule: map{tags: [str], query: str, match: str, filter_by: str}}
@optional {includes: [map{id!: str, position!: int}], excludes: [map{id!: str}], filter_by: str, remove_matched_tokens: bool, metadata: map, sort_by: str, replace_query: str, filter_curated_hits: bool, effective_from_ts: int, effective_to_ts: int, stop_processing: bool, id: str}
@returns(200)
@errors {400}

@endpoint DELETE /curation_sets/{curationSetName}/items/{itemId}
@required {curationSetName: str, itemId: str}
@returns(200) {id: str}
@errors {404}

@endgroup

@group collections
@endpoint GET /collections/{collectionName}/documents/export
@required {collectionName: str}
@optional {exportDocumentsParameters: map}
@returns(200)
@errors {404}

@endpoint POST /collections/{collectionName}/documents/import
@required {collectionName: str}
@optional {importDocumentsParameters: map}
@returns(200)
@errors {400, 404}

@endpoint GET /collections/{collectionName}/documents/{documentId}
@required {collectionName: str, documentId: str}
@returns(200)
@errors {404}

@endpoint PATCH /collections/{collectionName}/documents/{documentId}
@required {collectionName: str, documentId: str}
@optional {dirty_values: str}
@returns(200)
@errors {404}

@endpoint DELETE /collections/{collectionName}/documents/{documentId}
@required {collectionName: str, documentId: str}
@returns(200)
@errors {404}

@endgroup

@group conversations
@endpoint GET /conversations/models
@returns(200)

@endpoint POST /conversations/models
@returns(201)
@errors {400}

@endpoint GET /conversations/models/{modelId}
@required {modelId: str}
@returns(200)

@endpoint PUT /conversations/models/{modelId}
@required {modelId: str}
@optional {id: str, model_name: str, api_key: str, history_collection: str, account_id: str, system_prompt: str, ttl: int, max_bytes: int, vllm_url: str}
@returns(200)

@endpoint DELETE /conversations/models/{modelId}
@required {modelId: str}
@returns(200)

@endgroup

@group keys
@endpoint GET /keys
@returns(200) {keys: [any]}

@endpoint POST /keys
@required {description: str, actions: [str], collections: [str]}
@optional {value: str, expires_at: int(int64)}
@returns(201)
@errors {400, 409}

@endpoint GET /keys/{keyId}
@required {keyId: int(int64)}
@returns(200)
@errors {404}

@endpoint DELETE /keys/{keyId}
@required {keyId: int(int64)}
@returns(200) {id: int(int64)}
@errors {400, 404}

@endgroup

@group aliases
@endpoint GET /aliases
@returns(200) {aliases: [map]}

@endpoint PUT /aliases/{aliasName}
@required {aliasName: str, collection_name: str}
@returns(200) {name: str, collection_name: str}
@errors {400, 404}

@endpoint GET /aliases/{aliasName}
@required {aliasName: str}
@returns(200) {name: str, collection_name: str}
@errors {404}

@endpoint DELETE /aliases/{aliasName}
@required {aliasName: str}
@returns(200) {name: str, collection_name: str}
@errors {404}

@endgroup

@group debug
@endpoint GET /debug
@returns(200) {version: str}

@endgroup

@group health
@endpoint GET /health
@returns(200) {ok: bool}

@endgroup

@group operations
@endpoint GET /operations/schema_changes
@returns(200)

@endpoint POST /operations/snapshot
@required {snapshot_path: str}
@returns(201) {success: bool}

@endpoint POST /operations/vote
@returns(200) {success: bool}

@endpoint POST /operations/cache/clear
@returns(200) {success: bool}

@endpoint POST /operations/db/compact
@returns(200) {success: bool}

@endgroup

@group config
@endpoint POST /config
@required {log-slow-requests-time-ms: int}
@returns(200) {success: bool}

@endgroup

@group multi_search
@endpoint POST /multi_search
@required {multiSearchParameters: map, searches: [any]}
@optional {union: bool=false}
@returns(200) {results: [any], conversation: map{answer: str, conversation_history: [map], conversation_id: str, query: str}}
@errors {400}

@endgroup

@group analytics
@endpoint POST /analytics/events
@required {name: str, event_type: str, data: map{user_id: str, doc_id: str, doc_ids: [str], q: str, analytics_tag: str}}
@returns(200) {ok: bool}
@errors {400}

@endpoint GET /analytics/events
@required {user_id: str, name: str, n: int}
@returns(200) {events: [map]}
@errors {400}

@endpoint POST /analytics/flush
@returns(200) {ok: bool}

@endpoint GET /analytics/status
@returns(200) {popular_prefix_queries: int, nohits_prefix_queries: int, log_prefix_queries: int, query_log_events: int, query_counter_events: int, doc_log_events: int, doc_counter_events: int}

@endpoint POST /analytics/rules
@returns(200)
@errors {400}

@endpoint GET /analytics/rules
@optional {rule_tag: str}
@returns(200)

@endpoint PUT /analytics/rules/{ruleName}
@required {ruleName: str}
@optional {name: str, rule_tag: str, params: map{destination_collection: str, limit: int, capture_search_requests: bool, meta_fields: [str], expand_query: bool, counter_field: str, weight: int}}
@returns(200)
@errors {400}

@endpoint GET /analytics/rules/{ruleName}
@required {ruleName: str}
@returns(200)
@errors {404}

@endpoint DELETE /analytics/rules/{ruleName}
@required {ruleName: str}
@returns(200)
@errors {404}

@endgroup

@group metrics.json
@endpoint GET /metrics.json
@returns(200)

@endgroup

@group stats.json
@endpoint GET /stats.json
@returns(200) {delete_latency_ms: num(double), delete_requests_per_second: num(double), import_latency_ms: num(double), import_requests_per_second: num(double), latency_ms: map, overloaded_requests_per_second: num(double), pending_write_batches: num(double), requests_per_second: map, search_latency_ms: num(double), search_requests_per_second: num(double), total_requests_per_second: num(double), write_latency_ms: num(double), write_requests_per_second: num(double)}

@endgroup

@group stopwords
@endpoint GET /stopwords
@returns(200) {stopwords: [map]}

@endpoint PUT /stopwords/{setId}
@required {setId: str, stopwords: [str]}
@optional {locale: str}
@returns(200) {id: str, stopwords: [str], locale: str}
@errors {400}

@endpoint GET /stopwords/{setId}
@required {setId: str}
@returns(200) {stopwords: map{id: str, stopwords: [str], locale: str}}
@errors {404}

@endpoint DELETE /stopwords/{setId}
@required {setId: str}
@returns(200) {id: str}
@errors {404}

@endgroup

@group presets
@endpoint GET /presets
@returns(200) {presets: [any]}

@endpoint GET /presets/{presetId}
@required {presetId: str}
@returns(200)
@errors {404}

@endpoint PUT /presets/{presetId}
@required {presetId: str, value: any}
@returns(200)
@errors {400}

@endpoint DELETE /presets/{presetId}
@required {presetId: str}
@returns(200) {name: str}
@errors {404}

@endgroup

@group stemming
@endpoint GET /stemming/dictionaries
@returns(200) {dictionaries: [str]}

@endpoint GET /stemming/dictionaries/{dictionaryId}
@required {dictionaryId: str}
@returns(200) {id: str, words: [map]}
@errors {404}

@endpoint POST /stemming/dictionaries/import
@required {id: str}
@returns(200)
@errors {400}

@endgroup

@group nl_search_models
@endpoint GET /nl_search_models
@returns(200)

@endpoint POST /nl_search_models
@returns(201)
@errors {400}

@endpoint GET /nl_search_models/{modelId}
@required {modelId: str}
@returns(200)
@errors {404}

@endpoint PUT /nl_search_models/{modelId}
@required {modelId: str}
@returns(200)
@errors {400, 404}

@endpoint DELETE /nl_search_models/{modelId}
@required {modelId: str}
@returns(200) {id: str}
@errors {404}

@endgroup

@end