Introduction

Welcome to the Typesense API documentation. This documentation itself is open source. Please leave your feedback as issues on the GitHub repo or send us a pull-request to contribute edits.

To learn how to install and run Typesense, see our getting started guide instead.

API clients

At the moment, we have API clients for Javascript, PHP, Python, and Ruby.

We recommend that you use our API client library if it is available for your language.

• Javascript
• Php
• Python
• Ruby

// Node.js
npm install typesense

// Browser
<script src="dist/typesense.min.js"></script>

composer require typesense/typesense-php

pip install typesense

gem install typesense

If you're using our Javascript client to access Typesense directly from the browser, be sure to start the Typesense server with the --enable-cors flag.

Authentication

• Javascript
• Php
• Python
• Ruby
• Shell

/*
 *  Our Javascript client library works on both the server and the browser.
 *  When using the library on the browser, please be sure to use the
 *  search-only API Key rather than the master API key since the latter
 *  has write access to Typesense and you don't want to expose that.
 */
let client = new Typesense.Client({
  'nodes': [{
    'host': 'localhost',
    'port': '8108',
    'protocol': 'http',
  }],

  'apiKey': '<API_KEY>',
  'connectionTimeoutSeconds': 2
})

use Typesense\Client;

$client = new Client(
  [
    'nodes'        => [
      [
        'host'     => 'localhost',
        'port'     => '8108',
        'protocol' => 'http',
      ],
    ],
    'api_key'      => '<API_KEY>',
    'connection_timeout_seconds' => 2,
  ]
);

import typesense

client = typesense.Client({
  'nodes': [{
    'host': 'localhost',
    'port': '8108',
    'protocol': 'http',
  }],

  'api_key': '<API_KEY>',
  'connection_timeout_seconds': 2
})

require 'typesense'

client = Typesense::Client.new(
  nodes: [
    {
      host:     'localhost',
      port:     8108,
      protocol: 'http'
    }
  ],

  api_key:  '<API_KEY>',
  connection_timeout_seconds: 2
)

# API authentication is done via the `X-TYPESENSE-API-KEY` HTTP header.
curl -H "X-TYPESENSE-API-KEY: <API_KEY>" "http://localhost:8108/collections"

Usage

In Typesense, a group of related documents is called a collection. A collection is roughly equivalent to a table in a relational database.

Create a collection

When a collection is created, we give it a name and describe the fields that will be indexed from the documents that are added to the collection.

Your documents can contain other fields not mentioned in the collection's schema - they will be stored but not indexed.

• Javascript
• Php
• Python
• Ruby
• Shell

let schema = {
  'name': 'companies',
  'num_documents': 0,
  'fields': [
    {
      'name': 'company_name',
      'type': 'string',
      'facet': false
    },
    {
      'name': 'num_employees',
      'type': 'int32',
      'facet': false
    },
    {
      'name': 'country',
      'type': 'string',
      'facet': true
    }
  ],
  'default_sorting_field': 'num_employees'
}

client.collections().create(schema)

$schema = [
  'name'      => 'companies',
  'fields'    => [
    [
      'name'  => 'company_name',
      'type'  => 'string'
    ],
    [
      'name'  => 'num_employees',
      'type'  => 'int32'
    ],
    [
      'name'  => 'country',
      'type'  => 'string',
      'facet' => true
    ]
  ],
  'default_sorting_field' => 'num_employees'
]

$client->collections->create($schema)

schema = {
  'name': 'companies',
  'fields': [
    {
      'name'  :  'company_name',
      'type'  :  'string'
    },
    {
      'name'  :  'num_employees',
      'type'  :  'int32'
    },
    {
      'name'  :  'country',
      'type'  :  'string',
      'facet' :  True
    }
  ],
  'default_sorting_field': 'num_employees'
}

client.collections.create(schema)

schema = {
  'name'      => 'companies',
  'fields'    => [
    {
      'name'  => 'company_name',
      'type'  => 'string'
    },
    {
      'name'  => 'num_employees',
      'type'  => 'int32'
    },
    {
      'name'  => 'country',
      'type'  => 'string',
      'facet' => true
    }
  ],
  'default_sorting_field' => 'num_employees'
}

client.collections.create(schema)

curl "http://localhost:8108/collections" -X POST -H "Content-Type: application/json" \
       -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
         "name": "companies",
         "fields": [
           {"name": "company_name", "type": "string" },
           {"name": "num_employees", "type": "int32" },
           {"name": "country", "type": "string", "facet": true }
         ],
         "default_sorting_field": "num_employees"
       }'

Sample response

• Json

{
  "name": "companies",
  "num_documents": 0,
  "fields": [
    {"name": "company_name", "type": "string" },
    {"name": "num_employees", "type": "int32" },
    {"name": "country", "type": "string", "facet": true }
  ],
  "default_sorting_field": "num_employees"
}

Definition

POST ${TYPESENSE_HOST}/collections

Arguments

Supported search field types

Typesense allows you to index the following types of fields:

You can define an array or multi-valued field by suffixing a [] at the end:

Index a document

A document to be indexed in a given collection must conform to the schema of the collection.

If the document contains an id field of type string, Typesense would use that field as the identifier for the document. Otherwise, Typesense would assign an identifier of its choice to the document. Note that the id should not include spaces or any other characters that require encoding in urls.

• Javascript
• Php
• Python
• Ruby
• Shell

let document = {
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}

client.collections('companies').documents().create(document)

$document = [
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
]

$client->collections['companies']->documents->create($document)

document = {
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}

client.collections['companies'].documents.create(document)

document = {
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
}

client.collections['companies'].documents.create(document)

curl "http://localhost:8108/collections/companies/documents" -X POST \
        -H "Content-Type: application/json" \
        -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
        -d '{
          "id": "124",
          "company_name": "Stark Industries",
          "num_employees": 5215,
          "country": "USA"
        }'

Upserting a document

You can also upsert a document.

• Javascript
• Php
• Python
• Ruby
• Shell

let document = {
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}

client.collections('companies').documents().upsert(document)

$document = [
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
]

$client->collections['companies']->documents->upsert($document)

document = {
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}

client.collections['companies'].documents.upsert(document)

document = {
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
}

client.collections['companies'].documents.upsert(document)

curl "http://localhost:8108/collections/companies/documents?action=upsert" -X POST \
        -H "Content-Type: application/json" \
        -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
        -d '{
          "id": "124",
          "company_name": "Stark Industries",
          "num_employees": 5215,
          "country": "USA"
        }'

To index multiple documents at the same time, in a batch/bulk operation, see importing documents.

Sample Response

• Json

{
  "id": "124",
  "company_name": "Stark Industries",
  "num_employees": 5215,
  "country": "USA"
}

Definition

POST ${TYPESENSE_HOST}/collections/:collection/documents

Search a collection

In Typesense, a search consists of a query against one or more text fields and a list of filters against numerical or facet fields. You can also sort and facet your results.

• Javascript
• Php
• Python
• Ruby
• Shell

let searchParameters = {
  'q'         : 'stark',
  'query_by'  : 'company_name',
  'filter_by' : 'num_employees:>100',
  'sort_by'   : 'num_employees:desc'
}

client.collections('companies').documents().search(searchParameters)

$searchParameters = [
  'q'         => 'stark',
  'query_by'  => 'company_name',
  'filter_by' => 'num_employees:>100',
  'sort_by'   => 'num_employees:desc'
]

$client->collections['companies']->documents->search($searchParameters)

search_parameters = {
  'q'         : 'stark',
  'query_by'  : 'company_name',
  'filter_by' : 'num_employees:>100',
  'sort_by'   : 'num_employees:desc'
}

client.collections['companies'].documents.search(search_parameters)

search_parameters = {
  'q'         => 'stark',
  'query_by'  => 'company_name',
  'filter_by' => 'num_employees:>100',
  'sort_by'   => 'num_employees:desc'
}

client.collections['companies'].documents.search(search_parameters)

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/companies/documents/search\
?q=stark&query_by=company_name&filter_by=num_employees:>100\
&sort_by=num_employees:desc"

Sample response

• Json

{
  "facet_counts": [],
  "found": 1,
  "out_of": 1,
  "page": 1,
  "request_params": { "q" : "" },
  "search_time_ms": 1,
  "hits": [
    {
      "highlights": [
        {
          "field": "company_name",
          "snippet": "<mark>Stark</mark> Industries",
          "matched_tokens": ["Stark"]
        }
      ],
      "document": {
        "id": "124",
        "company_name": "Stark Industries",
        "num_employees": 5215,
        "country": "USA"
      }
    }
  ]
}

When a string[] field is queried, the highlights structure would include the corresponding matching array indices of the snippets. For e.g:

• Json

{
      ...
      "highlights": [
        {
          "field": "addresses",
          "indices": [0,2],
          "snippets": [
            "10880 <mark>Malibu</mark> Point, <mark>Malibu,</mark> CA 90265",
            "10000 <mark>Malibu</mark> Point, <mark>Malibu,</mark> CA 90265"
          ],
          "matched_tokens": [
            ["Malibu", "Malibu"],
            ["Malibu", "Malibu"]
          ]
        }
      ],
      ...
}

Group by

You can aggregate search results into groups or buckets by specify one or more group_by fields.

Grouping hits this way is useful in:

• Deduplication: By using one or more group_by fields, you can consolidate items and remove duplicates in the search results. For example, if there are multiple shoes of the same size, by doing a group_by=size&group_limit=1, you ensure that only a single shoe of each size is returned in the search results.
• Correcting skew: When your results are dominated by documents of a particular type, you can use group_by and group_limit to correct that skew. For example, if your search results for a query contains way too many documents of the same brand, you can do a group_by=brand&group_limit=3 to ensure that only the top 3 results of each brand is returned in the search results.

NOTE: To group on a particular field, it must be a faceted field.

Grouping returns the hits in a nested structure, that's different from the plain JSON response format we saw earlier. Let's repeat the query we made earlier with a group_by parameter:

• Javascript
• Php
• Python
• Ruby
• Shell

let searchParameters = {
  'q'            : 'stark',
  'query_by'     : 'company_name',
  'filter_by'    : 'num_employees:>100',
  'sort_by'      : 'num_employees:desc',
  'group_by'     : 'country',
  'group_limit'  : '1'
}

client.collections('companies').documents().search(searchParameters)

$searchParameters = [
  'q'           => 'stark',
  'query_by'    => 'company_name',
  'filter_by'   => 'num_employees:>100',
  'sort_by'     => 'num_employees:desc',
  'group_by'    => 'country',
  'group_limit' => '1'
]

$client->collections['companies']->documents->search($searchParameters)

search_parameters = {
  'q'           : 'stark',
  'query_by'    : 'company_name',
  'filter_by'   : 'num_employees:>100',
  'sort_by'     : 'num_employees:desc',
  'group_by'    : 'country',
  'group_limit' : '1'
}

client.collections['companies'].documents.search(search_parameters)

search_parameters = {
  'q'           => 'stark',
  'query_by'    => 'company_name',
  'filter_by'   => 'num_employees:>100',
  'sort_by'     => 'num_employees:desc',
  'group_by'    => 'country',
  'group_limit' => '1'
}

client.collections['companies'].documents.search(search_parameters)

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/companies/documents/search\
?q=stark&query_by=company_name&filter_by=num_employees:>100\
&sort_by=num_employees:desc&group_by=country&group_limit=1"

• Json

{
  "facet_counts": [],
  "found": 1,
  "out_of": 1,
  "page": 1,
  "request_params": { "q" : "" },
  "search_time_ms": 1,
  "grouped_hits": [
    {
      "group_key": ["USA"],
      "hits": [
        {
          "highlights": [
            {
              "field": "company_name",
              "snippet": "<mark>Stark</mark> Industries"
            }
          ],
          "document": {
            "id": "124",
            "company_name": "Stark Industries",
            "num_employees": 5215,
            "country": "USA"
          }
        }
      ]
    }
  ]
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/documents/search

Arguments

Retrieve a document

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').documents('124').retrieve()

$client->collections['companies']->documents['124']->retrieve()

client.collections['companies'].documents['124'].retrieve()

client.collections['companies'].documents['124'].retrieve

$ curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X GET \
      "http://localhost:8108/collections/companies/documents/124"

Sample response

• Json

{
  "id": "124",
  "company_name": "Stark Industries",
  "num_employees": 5215,
  "country": "USA"
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/documents/:id

Update a document

Update an individual document from a collection by using its id. The update can be partial, as shown below:

• Javascript
• Php
• Python
• Ruby
• Shell

let document = {
  'company_name': 'Stark Industries',
  'num_employees': 5500
}

client.collections('companies').documents('124').update(document)

$document = [
  'company_name'  => 'Stark Industries',
  'num_employees' => 5500
]

$client->collections['companies']->documents['124']->update($document)

document = {
  'company_name': 'Stark Industries',
  'num_employees': 5500
}

client.collections['companies'].documents['124'].update(document)

document = {
  'company_name'  => 'Stark Industries',
  'num_employees' => 5500
}

client.collections['companies'].documents['124'].update(document)

curl "http://localhost:8108/collections/companies/documents/124" -X PATCH \
        -H "Content-Type: application/json" \
        -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
        -d '{
          "company_name": "Stark Industries",
          "num_employees": 5500
        }'

Sample response

• Json

{
  "company_name": "Stark Industries",
  "num_employees": 5500
}

Definition

PATCH ${TYPESENSE_HOST}/collections/:collection/documents/:id

Deleting documents

Delete an individual document from a collection by using its id.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').documents('124').delete()

$client->collections['companies']->documents['124']->delete()

client.collections['companies'].documents['124'].delete()

client.collections['companies'].documents['124'].delete

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X DELETE \
    "http://localhost:8108/collections/companies/documents/124"

Sample response

• Json

{
  "id": "124",
  "company_name": "Stark Industries",
  "num_employees": 5215,
  "country": "USA"
}

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/documents/:id

You can also delete a bunch of documents that match a specific filter condition:

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').documents().delete({'filter_by': 'num_employees:>100'})

$client->collections['companies']->documents->delete(['filter_by' => 'num_employees:>100']));

client.collections['companies'].documents.delete_({'filter_by': 'num_employees:>100'})

client.collections['companies'].documents.delete(filter_by: 'num_employees:>100')

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X DELETE \
"http://localhost:8108/collections/companies/documents?filter_by=num_employees:>=100&batch_size=100"

Use the batch_size parameter to control the number of documents that should deleted at a time. A larger value will speed up deletions, but will impact performance of other operations running on the server.

Sample response

• Json

{
  "num_deleted": 24
}

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/documents?filter_by=X&batch_size=N

Retrieve a collection

Retrieve the details of a collection, given its name.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').retrieve()

$client->collections['companies']->retrieve()

client.collections['companies'].retrieve()

client.collections['companies'].retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X GET
    "http://localhost:8108/collections/companies"

Sample response

• Json

{
  "name": "companies",
  "num_documents": 1250,
  "fields": [
    {"name": "company_name", "type": "string"},
    {"name": "num_employees", "type": "int32"},
    {"name": "country", "type": "string", "facet": true}
  ],
  "default_sorting_field": "num_employees"
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection

Export documents from a collection

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').documents().export()

$client->collections['companies']->documents->export()

client.collections['companies'].documents.export()

client.collections['companies'].documents.export

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X GET
    "http://localhost:8108/collections/companies/documents/export"

Sample response

• Jsonlines

{"id": "124", "company_name": "Stark Industries", "num_employees": 5215,\
"country": "US"}
{"id": "125", "company_name": "Future Technology", "num_employees": 1232,\
"country": "UK"}
{"id": "126", "company_name": "Random Corp.", "num_employees": 531,\
"country": "AU"}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/documents/export

Import documents into a collection

The documents to be imported can be either an array of document objects or be formatted as a newline delimited JSON string (see JSONL).

Indexing multiple documents at the same time

You can index multiple documents via the import API.

• Javascript
• Php
• Python
• Ruby

let documents = [{
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}]

client.collections('companies').documents().import(documents, {action: 'upsert'})

$documents = [[
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
]]

$client->collections['companies']->documents->import($documents, ['action' => 'upsert'])

documents = [{
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}]

client.collections['companies'].documents.import_(documents, {'action': 'upsert'})

documents = [{
  'id'            => '124',
  'company_name'  => 'Stark Industries',
  'num_employees' => 5215,
  'country'       => 'USA'
}]

client.collections['companies'].documents.import(documents, action: 'upsert')

The other allowed action modes are create and update.

Action modes

Importing a JSONL file

You can feed the output of a Typesense export operation directly as import to the import end-point since both use JSONL.

Here's an example file:

• Jsonl

{"id": "1", "company_name": "Stark Industries", "num_employees": 5215, "country": "USA"}
{"id": "2", "company_name": "Orbit Inc.", "num_employees": 256, "country": "UK"}

You can import the above documents.jsonl file like this.

• Javascript
• Php
• Python
• Ruby
• Shell

const documentsInJsonl = await fs.readFile("documents.jsonl");
client.collections('companies').documents().import(documentsInJsonl, {action: 'create'});

$documentsInJsonl = file_get_contents('documents.jsonl');
client.collections['companies'].documents.import($documentsInJsonl, ['action' => 'create'])

with open('documents.jsonl') as jsonl_file:
  client.collections['companies'].documents.import_jsonl(jsonl_file.read(), {'action': 'create'})

documents_jsonl = File.read('documents.jsonl')
collections['companies'].documents.import(documents_jsonl, action: 'create')

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X POST --data-binary @documents.jsonl \
"http://localhost:8108/collections/companies/documents/import?action=create"

In the example above, we're importing the documents with the action flag set to create. This means that the documents will be inserted only if a document with the same id is not already found.

As we have seen earlier, you can also use the upsert and update actions. If you don't provide an action, the default mode is create.

Configuring the batch size used for import

By default, Typesense ingests 40 documents at a time into Typesense. To increase this value, use the batch_size parameter.

• Javascript
• Php
• Python
• Ruby
• Shell

const documentsInJsonl = await fs.readFile("documents.jsonl");
client.collections('companies').documents().import(documentsInJsonl, {batch_size: 100});

$documentsInJsonl = file_get_contents('documents.jsonl');
client.collections['companies'].documents.import($documentsInJsonl, ['batch_size' => 100])

with open('documents.jsonl') as jsonl_file:
  client.collections['companies'].documents.import_jsonl(jsonl_file.read(), {'batch_size': 100})

documents_jsonl = File.read('documents.jsonl')
collections['companies'].documents.import(documents_jsonl, batch_size: 100)

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X POST --data-binary @documents.jsonl \
"http://localhost:8108/collections/companies/documents/import?batch_size=100"

NOTE: Larger batch sizes will consume larger transient memory during import.

Sample response

• Jsonlines

{"success": true}
{"success": true}

Each line of the response indicates the result of each document present in the request body (in the same order). If the import of a single document fails, it does not affect the other documents.

If there is a failure, the response line will include a corresponding error message and as well as the actual document content. For example, the second document had an import failure in the following response:

• Json

{"success": true}
{"success": false, "error": "Bad JSON.", "document": "[bad doc"}

Definition

POST ${TYPESENSE_HOST}/collections/:collection/documents/import

List all collections

Returns a summary of all your collections. The collections are returned sorted by creation date, with the most recent collections appearing first.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections().retrieve()

$client->collections->retrieve()

client.collections.retrieve()

client.collections.retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" "http://localhost:8108/collections"

Sample response

• Json

[
  {
    "num_documents": 1250,
    "name": "companies",
    "fields": [
      {"name": "company_name", "type": "string"},
      {"name": "num_employees", "type": "int32"},
      {"name": "country", "type": "string", "facet": true}
    ],
    "default_sorting_field": "num_employees"
  },
  {
    "num_documents": 1250,
    "name": "ceos",
    "fields": [
      {"name": "company_name", "type": "string"},
      {"name": "full_name", "type": "string"},
      {"name": "from_year", "type": "int32"}
    ],
    "default_sorting_field": "num_employees"
  }
]

Definition

GET ${TYPESENSE_HOST}/collections

Drop a collection

Permanently drops a collection. This action cannot be undone. For large collections, this might have an impact on read latencies.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').delete()

$client->collections['companies']->delete()

client.collections['companies'].delete()

client.collections['companies'].delete

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X DELETE
    "http://localhost:8108/collections/companies"

Sample response

• Json

{
  "name": "companies",
  "num_documents": 1250,
  "fields": [
    {"name": "company_name", "type": "string"},
    {"name": "num_employees", "type": "int32"},
    {"name": "country", "type": "string", "facet": true}
  ],
  "default_sorting_field": "num_employees"
}

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection

API Keys

Typesense allows you to create API Keys with fine-grain access control. You can restrict access on both a per-collection and per-action level.

We will be using the initial bootstrap key that you started Typesense with (via --api-key>) to create additional keys. It's strongly recommended that you don't use the bootstrap API key directly in your production applications. Instead you want to generate an appropriately-scoped key for the application at hand.

Create an API Key

Let's begin by creating an API key that allows you to do all operations, i.e. it's effectively an admin key and is equivalent to the key that you start Typesense with (via --api-key).

• Javascript
• Php
• Python
• Ruby
• Shell

key = client.keys().create({
  'description': 'Admin key.',
  'actions': ['*'],
  'collections': ['*']
})

$key = $client->keys->create([
  'description' => 'Admin key.',
  'actions' => ['*'],
  'collections' => ['*']
])

key = client.keys.create({
  "description": "Admin key.",
  "actions": ["*"],
  "collections": ["*"]
})

key = client.keys.create({
  'description' => 'Admin key.',
  'actions' => ['*'],
  'collections' => ['*']
})

curl 'http://localhost:8108/keys' -X POST -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"description":"Admin key.","actions": ["*"], "collections": ["*"]}'

By setting both actions and collections to a wildcard ['*'] scope, we're able to create an admin key that gives you universal access. However, you should refrain from creating such widely scoped keys.

NOTE: The generated key is only returned during creation. You want to store this key carefully in a secure place.

Let's now see how we can create a search-only key that allows you to limit the key's scope to only the search action, and also for only a specific collection.

• Javascript
• Php
• Python
• Ruby
• Shell

client.keys().create({
  'description': 'Admin key.',
  'actions': ['documents:search'],
  'collections': ['companies']
})

$client->keys->create([
  'description' => 'Search-only companies key.',
  'actions' => ['documents:search'],
  'collections' => ['companies']
])

client.keys.create({
  "description": "Search-only companies key.",
  "actions": ["documents:search"],
  "collections": ["companies"]
})

client.keys.create({
  'description' => 'Search-only companies key.',
  'actions' => ['documents:search'],
  'collections' => ['companies']
})

curl 'http://localhost:8108/keys' -X POST -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"description":"Search-only companies key.","actions": ["documents:search"], "collections": ["companies"]}'

By setting the actions scope to ["documents:search"] and the collections scope to ["companies"], we can generate a key that is allowed to only conduct searches on the companies collection.

Sample response

• Json

{
  "actions": [
    "*"
  ],
  "collections": [
    "*"
  ],
  "description": "Admin key.",
  "id": 1,
  "value": "k8pX5hD0793d8YQC5aD1aEPd7VleSuGP"
}

Definition

POST ${TYPESENSE_HOST}/keys

Arguments

Sample actions

Retrieve an API Key

Retrieve (metadata about) a key.

• Javascript
• Php
• Python
• Ruby
• Shell

key = client.keys(1).retrieve()

$key = $client->keys[1]->retrieve()

key = client.keys[1].retrieve()

key = client.keys[1].retrieve

curl 'http://localhost:8108/keys/1' -X GET -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "actions": [ "documents:search" ],
  "collections": [ "*" ],
  "description": "Search-only key.",
  "id": 1,
  "value_prefix": "vxpx"
}

Notice how only the key prefix is returned when you retrieve a key. Due to security reasons, only the create endpoint returns the full API key.

Definition

GET ${TYPESENSE_HOST}/keys/:id

List all keys

Retrieve (metadata about) all keys.

• Javascript
• Php
• Python
• Ruby
• Shell

client.keys().retrieve()

$client->keys->retrieve()

client.keys.retrieve()

client.keys.retrieve

curl 'http://localhost:8108/keys' -X GET -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "keys": [
    {
      "actions": [
        "documents:search"
      ],
      "collections": [
        "users"
      ],
      "description": "Search-only key.",
      "id": 1,
      "value_prefix": "iKBT"
    },
    {
      "actions": [
        "documents:search"
      ],
      "collections": [
        "users"
      ],
      "description": "Search-only key.",
      "id": 2,
      "value_prefix": "wst8"
    }
  ]
}

Notice how only the key prefix is returned when you retrieve a key. Due to security reasons, only the create endpoint returns the full API key.

Definition

GET ${TYPESENSE_HOST}/keys

Delete API Key

Delete an API key given its ID.

• Javascript
• Php
• Python
• Ruby
• Shell

key = client.keys(1).delete()

$key = $client->keys[1]->delete()

key = client.keys[1].delete()

key = client.keys[1].delete

curl 'http://localhost:8108/keys/1' -X DELETE -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "id": 1
}

Definition

DELETE ${TYPESENSE_HOST}/keys/:id

Generate Scoped Search Key

You can generate scoped search API keys that have embedded search parameters in them. This is useful for example when you have multi-tenant data indexed in your Typesense instance, but only want your users to access their own subset of the data.

To do this, you can embed a filter in a generated scoped search API key. When you use that key for search operations, those filters will get automatically applied and cannot be overriden.

We can generate scoped search API keys without having to make any calls to the Typesense server. We use an API key that we previously generated with a search scope, create an HMAC digest of the parameters with this key and use that as the API key. Our client libraries handle this logic for you, but you can also generate scoped search API keys from the command line.

Note: Remember to never expose your main search key client-side, since exposing the main search key will allow anyone to query the entire data set without your embedded search parameters.

• Javascript
• Php
• Python
• Ruby
• Shell

keyWithSearchPermissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
client.keys().generateScopedSearchKey(keyWithSearchPermissions, {'filter_by': 'company_id:124', 'expires_at': 1611590465})

$keyWithSearchPermissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
$client->keys()->generateScopedSearchKey($keyWithSearchPermissions, ['filter_by' => 'company_id:124', 'expires_at' => 1611590465])

key_with_search_permissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
client.keys().generate_scoped_search_key(key_with_search_permissions, {"filter_by": "company_id:124", "expires_at": 1611590465})

key_with_search_permissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
client.keys().generate_scoped_search_key(key_with_search_permissions, {'filter_by': 'company_id:124', 'expires_at': 1611590465})

KEY_WITH_SEARCH_PERMISSIONS="RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127"
EMBEDDED_SEARCH_PARAMETERS_JSON='{"filter_by":"company_id:124","expires_at":1611590465}'

digest=$(echo -n $EMBEDDED_SEARCH_PARAMETERS_JSON | openssl dgst -sha256 -hmac $KEY_WITH_SEARCH_PERMISSIONS -binary | base64)

scoped_api_key=$(echo -n "${digest}${KEY_WITH_SEARCH_PERMISSIONS:0:4}${EMBEDDED_SEARCH_PARAMETERS_JSON}" | base64)

echo $scoped_api_key

Sample response

• Json

"SC9sT0hncHFwTHNFc3U3d3psRDZBUGNXQUViQUdDNmRHSmJFQnNnczJ4VT1STjIzeyJmaWx0ZXJfYnkiOiJjb21wYW55X2lkOjEyNCJ9"

You can also set a custom expires_at for a scoped API key. The expiration for a scoped API key should be less than the expiration of the parent API key with which it is generated.

Curation

While Typesense makes it really easy and intuitive to deliver great search results, sometimes you might want to promote certain documents over others. Or, you might want to exclude certain documents from a query's result set.

Using overrides, you can include or exclude specific documents for a given query.

Create or update an override

In the following example, we are overriding the search results by placing the documents with ids 422 and 54 in the first and second positions respectively via the includes condition. Additionally, we're ensuring that the document with id 287 is not returned at all via the excludes condition. You need to specify only one of exclude or include.

Note how we are applying these overrides to an exact match of the query apple. Instead, if we want to match all queries that contained the word apple, we will use the contains match instead.

• Javascript
• Php
• Python
• Ruby
• Shell

override = {
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}

// Creates/updates an override called `customize-apple` in the `companies` collection
client.collections('companies').overrides().upsert('customize-apple', override)

$override = [
  "rule" => [
    "query" => "apple",
    "match" => "exact"
  ],
  "includes" => [
    ["id" => "422", "position" => 1],
    ["id" => "54", "position" => 2]
  ],
  "excludes" => [
    ["id" => "287"]
  ]
]

# Creates/updates an override called `customize-apple` in the `companies` collection
$client->collections['companies']->overrides->upsert('customize-apple', $override)

override = {
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}

# Creates/updates an override called `customize-apple` in the `companies` collection
client.collections['companies'].overrides.upsert('customize-apple', override)

override = {
  "rule" => {
    "query" => "apple",
    "match" => "exact"
  },
  "includes" => [
    {"id" => "422", "position" => 1},
    {"id" => "54", "position" => 2}
  ],
  "excludes" => [
    {"id" => "287"}
  ]
}

# Creates/updates an override called `customize-apple` in the `companies` collection
client.collections['companies'].overrides.upsert('customize-apple', override)

curl "http://localhost:8108/collections/companies/overrides/customize-apple" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
  "rule": {
    "query": "apple",
    "match": "exact"
  },
  "includes": [
    {"id": "422", "position": 1},
    {"id": "54", "position": 2}
  ],
  "excludes": [
    {"id": "287"}
  ]
}'

Sample response

• Json

{
  "id": "customize-apple",
  "excludes": [
    {
      "id": "287"
    }
  ],
  "includes": [
    {
      "id": "422",
      "position": 1
    },
    {
      "id": "54",
      "position": 2
    }
  ],
  "rule": {
    "match": "exact",
    "query": "apple"
  }
}

Definition

PUT ${TYPESENSE_HOST}/collections/:collection/overrides/:id

Arguments

List all overrides

Listing all overrides associated with a given collection.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').overrides().retrieve

$client->collections['companies']->overrides->retrieve()

client.collections['companies'].overrides.retrieve()

client.collections['companies'].overrides.retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/companies/overrides"

Sample response

• Json

{
  "overrides":[
    {
      "id":"customize-apple",
      "excludes":[
        {
          "id":"287"
        }
      ],
      "includes":[
        {
          "id":"422",
          "position":1
        },
        {
          "id":"54",
          "position":2
        }
      ],
      "rule":{
        "match":"exact",
        "query":"apple"
      }
    }
  ]
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/overrides

Delete an override

Deleting an override associated with a collection.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('companies').overrides('customize-apple').delete()

$client->collections['companies']->overrides['customize-apple'].delete()

client.collections['companies'].overrides['customize-apple'].delete()

client.collections['companies'].overrides['customize-apple'].delete

curl "http://localhost:8108/collections/companies/overrides/customize-apple" -X DELETE \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "id": "customize-apple"
}

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/overrides/:id

Collection Alias

An alias is a virtual collection name that points to a real collection. If you're familiar with symbolic links on Linux, it's very similar to that.

Aliases are useful when you want to reindex your data in the background on a new collection and switch your application to it without any changes to your code. Let's take an example.

Let's say we have a collection called companies_june10 and an alias called companies pointing to that collection.

collection ---> companies_june10

On the next day (June 11), we will create a new collection called companies_june11 and start indexing the documents in the background into this collection. When we are done indexing, if we updated the companies alias to point to this new collection, your application would immediately start querying against the freshly indexed collection.

collection ---> companies_june11

Convenient isn't it? Let's now look at how we can create, update and manage aliases.

Create or Update an alias

• Javascript
• Php
• Python
• Ruby
• Shell

aliased_collection = {
  'collection_name': 'companies_june11'
}

// Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases().upsert('companies', aliased_collection)

$aliasedCollection = [
  'collection_name' => 'companies_june11'
]

# Creates/updates an alias called `companies` to the `companies_june11` collection
$client->aliases->upsert('companies', $aliasedCollection)

aliased_collection = {
  'collection_name': 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)

aliased_collection = {
  'collection_name' => 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)

curl "http://localhost:8108/aliases/companies" -X PUT \
    -H "Content-Type: application/json" \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
        "collection_name": "companies_june11"
    }'

Sample response

• Json

{
  "name": "companies",
  "collection_name": "companies_june11",
}

Definition

PUT ${TYPESENSE_HOST}/aliases/:alias

Arguments

Retrieve an alias

We can find out which collection an alias points to by fetching it.

• Javascript
• Php
• Python
• Ruby
• Shell

client.aliases('companies').retrieve()

$client->aliases['companies']->retrieve()

client.aliases['companies'].retrieve()

client.aliases['companies'].retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    "http://localhost:8108/aliases/companies"

Sample response

• Json

{
  "name": "companies",
  "collection_name": "companies_june11",
}

Definition

GET ${TYPESENSE_HOST}/aliases/:alias

List all aliases

List all aliases and the corresponding collections that they map to.

• Javascript
• Php
• Python
• Ruby
• Shell

client.aliases().retrieve()

$client->aliases->retrieve()

client.aliases.retrieve()

client.aliases.retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     "http://localhost:8108/aliases"

Sample response

• Json

{
  "aliases": [
    {
      "name": "companies",
      "collection_name": "companies_june11"
    },
    {
      "name": "employees",
      "collection_name": "employees_june11"
    }
  ]
}

Definition

GET ${TYPESENSE_HOST}/aliases

Delete an alias

• Javascript
• Php
• Python
• Ruby
• Shell

client.aliases('companies').delete()

$client->aliases['companies']->delete()

client.aliases['companies'].delete()

client.aliases['companies'].delete

curl "http://localhost:8108/aliases/companies" -X DELETE
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "name": "companies",
  "collection_name": "companies_june11"
}

Definition

DELETE ${TYPESENSE_HOST}/aliases/:alias

Synonyms

The synonyms feature allows you to define search terms that should be considered equivalent. For eg: when you define a synonym for sneaker as shoe, searching for sneaker will now return all records with the word shoe in them, in addition to records with the word sneaker.

Typesense supports two types of synonyms:

Multi-way synonyms

Defining words ABC, DEF and XYZ (for eg) as multi-way synonyms will cause searches for any one of those words (eg: DEF) to return records containing at least one of the words in the synonym set (eg: records with ABC or DEF or KYX are returned).

One-way synonyms

Defining the words DEF and XYZ as one-way synonyms of ABC will cause searches for DEF or XYZ to return records containing ABC.

Create or update a multi-way synonym

• Javascript
• Php
• Python
• Ruby
• Shell

synonym = {
  "synonyms": ["blazer", "coat", "jacket"]
}

// Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('coat-synonyms', synonym)

$synonym = [
  "synonyms" => ["blazer", "coat", "jacket"]
]

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
$client->collections['products']->synonyms->upsert('coat-synonyms', $synonym)

synonym = {
  "synonyms": ["blazer", "coat", "jacket"]
}

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('coat-synonyms', synonym)

synonym = {
  "synonyms" => ["blazer", "coat", "jacket"]
}

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('coat-synonyms', synonym)

curl "http://localhost:8108/collections/products/synonyms/coat-synonyms" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
  "synonyms": ["blazer", "coat", "jacket"]
}'

Sample response

• Json

{
  "id": "coat-synonyms",
  "synonyms": ["blazer", "coat", "jacket"]
}

Create or update a one-way synonym

• Javascript
• Php
• Python
• Ruby
• Shell

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

$synonym = [
  "root" => "blazer",
  "synonyms" => ["coat", "jacket"]
]

# Creates/updates a synonym called `blazer-synonyms` in the `products` collection
$client->collections['products']->synonyms->upsert('blazer-synonyms', $synonym)

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

# Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('blazer-synonyms', synonym)

synonym = {
  "root" => "blazer",
  "synonyms" => ["coat", "jacket"]
}

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('coat-synonyms', synonym)

curl "http://localhost:8108/collections/products/synonyms/coat-synonyms" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}'

Sample response

• Json

{
  "id":"coat-synonyms",
  "root":"blazer",
  "synonyms": ["coat", "jacket"]
}

Definition

PUT ${TYPESENSE_HOST}/collections/:collection/synonyms/:id

Arguments

Retrieve a synonym

We can retrieve a single synonym.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('products').synonyms('coat-synonyms').retrieve

$client->collections['products']->synonyms['coat-synonyms']->retrieve()

client.collections['products'].synonyms['coat-synonyms'].retrieve()

client.collections['products'].synonyms['coat-synonyms'].retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/products/synonyms/coat-synonyms"

Sample response

• Json

{
  "id": "coat-synonyms",
  "root":"",
  "synonyms": ["blazer", "coat", "jacket"]
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/synonyms/:id

List all synonyms

List all synonyms associated with a given collection.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('products').synonyms().retrieve

$client->collections['products']->synonyms->retrieve()

client.collections['products'].synonyms.retrieve()

client.collections['products'].synonyms.retrieve

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/products/synonyms"

Sample response

• Json

{
  "synonyms":[
    {
      "id": "coat-synonyms",
      "root": "blazer",
      "synonyms": ["coat", "jacket"]
    }
  ]
}

Definition

GET ${TYPESENSE_HOST}/collections/:collection/synonyms

Delete a synonym

Delete a synonym associated with a collection.

• Javascript
• Php
• Python
• Ruby
• Shell

client.collections('books').synonyms('coat-synonyms').delete()

$client->collections['books']->synonyms['coat-synonyms'].delete()

client.collections['books'].synonyms['coat-synonyms'].delete()

client.collections['books'].synonyms['coat-synonyms'].delete

curl "http://localhost:8108/collections/books/synonyms/coat-synonyms" -X DELETE \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "id": "coat-synonyms"
}

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/synonyms/:id

Cluster Operations

Create snapshot (for backups)

Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.

You can then backup the snapshot directory that gets created and later restore it as a data directory, as needed.

• Javascript
• Php
• Python
• Ruby
• Shell

client.operations.perform('snapshot', {'snapshot_path': '/tmp/typesense-data-snapshot'})

$client->operations->perform("snapshot", ["snapshot_path" => "/tmp/typesense-data-snapshot"])

client.operations.perform('snapshot', {'snapshot_path': '/tmp/typesense-data-snapshot'})

client.operations.perform('snapshot', {'snapshot_path': '/tmp/typesense-data-snapshot'})

curl "http://localhost:8108/operations/snapshot?snapshot_path=/tmp/typesense-data-snapshot" -X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "success": true
}

Definition

POST ${TYPESENSE_HOST}/operations/snapshot

Arguments

Re-elect Leader

Triggers a follower node to initiate the raft voting process, which triggers leader re-election.

The follower node that you run this operation against will become the new leader, once this command succeeds.

• Javascript
• Php
• Python
• Ruby
• Shell

client.operations.perform('vote')

$client->operations->perform("vote")

client.operations.perform('vote')

client.operations.perform('vote')

curl "http://localhost:8108/operations/vote" -X POST \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

Sample response

• Json

{
  "success": true
}

Definition

POST ${TYPESENSE_HOST}/operations/vote

What's new in 0.18.0

This release contains a few new features and important bug fixes.

• [Feature] Support for query synonyms.
• [Feature] Better search relevance when searching across multiple fields: addressed some edge cases in multi-field queries.
• [Feature] Ability to assign custom weights to each field being queried upon.
• [Feature] Total documents in a collection is now returned in every response via the `out_of` key.
• [Feature] Exclusion operator `-` for excluding individual query tokens from results.
• [Feature] Vote API for triggering rotation of leader.
• [Feature] On-demand snapshot API: allows you to create a backup with a single API call.
• [Feature] Support for expiry of API keys
• [Feature] Support regexp for defining allowed collection names of an API key.
• [Feature] Support operators in multi-valued numerical filter.
• [Feature] Support bulk imports of upto 3 GB in POST body.
• [Bug fix] Fixed an edge case in fuzzy search that missed some tokens during exact searches.
• [Bug fix] Prefix matches are assigned lesser importance than exact matches.
• [Bug fix] Debug end-point is now available even when node is not ready to serve searches.
• [Bug fix] Fixed >= operator not working well with negative values.
• [Bug fix] Fixed non-ascii characters not encoded properly in highlight snippet.
• [Bug fix] Fixed issue where duplicate results were returned across pages.
• [Bug fix] Fixed issue with pinned results being duplicated.
• [Performance] Faster snapshot transfer and copy in multi-regional clusters.
• [Performance] Speed up filters on numerical fields.

API errors

Typesense API uses standard HTTP response codes to indicate the success or failure of a request.

Codes in the 2xx range indicate success, codes in the 4xx range indicate an error given the information provided (e.g. a required parameter was omitted), and codes in the 5xx range indicate an error with the Typesense service itself.