Skip to content
Headless Platform

Similarity API

This API supports advanced search capabilities, which will allow clients to find similar documents base in the input.

Authentication

Section titled “Authentication”

Clients calling the API are required to add an authentication header with the valid authentication token.

Authorization: Bearer {ACCESS_TOKEN}

Examples

Section titled “Examples”

Nearest documents

Section titled “Nearest documents”

The similarity API allows the client to find the nearest document based off of a piece of text and a targeted field.

query FindNearestDocument {
  similarity(
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      }
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

sample response:

{
  "data": {
    "similarity": {
      "total": 1,
      "docs": [
        {
          "id": "rabbit:6",
          "score": 2.5204816,
          "data": {
            "ID": 1,
            "post_content": "Rabbit is happily running",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "George the rabbit",
            "post_type": "rabbit"
          }
        },
        {
          "id": "horse:7",
          "score": 2.2204816,
          "data": {
            "ID": 1,
            "post_content": "Horse in a field",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "Greg the horse",
            "post_type": "horse"
          }
        },
      ]
    }
  }
}

Using multiple fields

Section titled “Using multiple fields”

Users can choose up to three fields instead of just one, and apply boosting to those fields, provided the fields are indexed with the inference model.

Using a singular field is still supported, but not recommended. The API accepts either field or fields, but not both simultaneously.

You can use the boosting query to demote certain documents without excluding them from the search results.

Boost 0 -> 0.9 is decreasing relevance score
Boost 1.0 is not affecting the score (can be omitted, as it's the default behaviour)
Boost 1.1 -> 10.0` is increasing relevance score

At least one field is required, name is a required key, boost is optional.

query FindNearestDocumentWithMultipleFields {
    similarity(
        input: {
            nearest: {
                text: "eats carrots and is an animal",
                fields: [{name: "post_name"}]
            },
        }) {
        total
        docs {
            id
            score
            data
        }
    }
}
query FindNearestDocumentWithMultipleFieldWithBoost {
    similarity(
        input: {
            nearest: {
                text: "eats carrots and is an animal",
                fields: [
                    {name: "post_name", boost: 0.1},
                    {name: "post_content", boost: 10},
                    {name: "post_title", boost: 9}
                ]
            },
        }) {
        total
        docs {
            id
            score
            data
        }
    }
}

Here’s a sample response demonstrating how the score changes when boosting is applied using the same FindNearestDocument query:

sample response:

{
  "data": {
    "similarity": {
      "total": 6,
      "docs": [
        {
          "id": "rabbit:6",
          "score": 19.557358,
          "data": {
            "ID": 6,
            "post_content": "",
            "post_date": "2025-06-13T12:44:46",
            "post_date_gmt": "2025-06-13T12:44:46",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:46",
            "post_modified_gmt": "2025-06-13T12:44:46",
            "post_name": "rabbit-1",
            "post_status": "publish",
            "post_title": "Rabbit-1",
            "post_type": "rabbit",
            "post_url": "http://localhost:8000/rabbit/rabbit-1"
          }
        },
        {
          "id": "rabbit:7",
          "score": 14.139838,
          "data": {
            "ID": 7,
            "post_content": "",
            "post_date": "2025-06-13T12:44:47",
            "post_date_gmt": "2025-06-13T12:44:47",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:47",
            "post_modified_gmt": "2025-06-13T12:44:47",
            "post_name": "rabbit-2",
            "post_status": "publish",
            "post_title": "Rabbit-2",
            "post_type": "rabbit",
            "post_url": "http://localhost:8000/rabbit/rabbit-2"
          }
        },
        {
          "id": "page:2",
          "score": 3.59585,
          "data": {
            "ID": 2,
            "author": {
              "user_nicename": "admin"
            },
            "post_content": "This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:\n\n\n\nHi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)\n\n\n\n…or something like this:\n\n\n\nThe XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.\n\n\n\nAs a new WordPress user, you should go to your dashboard to delete this page and create new pages for your content. Have fun!",
            "post_date": "2025-06-13T12:44:24",
            "post_date_gmt": "2025-06-13T12:44:24",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:24",
            "post_modified_gmt": "2025-06-13T12:44:24",
            "post_name": "sample-page",
            "post_status": "publish",
            "post_title": "Sample Page",
            "post_type": "page",
            "post_url": "http://localhost:8000/sample-page"
          }
        },
        {
          "id": "zombie:4",
          "score": 0.9963488,
          "data": {
            "ID": 4,
            "post_content": "",
            "post_date": "2025-06-13T12:44:45",
            "post_date_gmt": "2025-06-13T12:44:45",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:45",
            "post_modified_gmt": "2025-06-13T12:44:45",
            "post_name": "zombie-1",
            "post_status": "publish",
            "post_title": "Zombie-1",
            "post_type": "zombie",
            "post_url": "http://localhost:8000/zombie/zombie-1"
          }
        },
        {
          "id": "post:1",
          "score": 0.646362,
          "data": {
            "ID": 1,
            "author": {
              "user_nicename": "admin"
            },
            "categories": [
              {
                "name": "Uncategorized",
                "slug": "uncategorized",
                "term_id": 1,
                "term_taxonomy_id": 1
              }
            ],
            "myCustomField": "my custom field value",
            "post_content": "Welcome to WordPress. This is your first post. Edit or delete it, then start writing!",
            "post_date": "2025-06-13T12:44:24",
            "post_date_gmt": "2025-06-13T12:44:24",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:24",
            "post_modified_gmt": "2025-06-13T12:44:24",
            "post_name": "hello-world",
            "post_status": "publish",
            "post_title": "Hello world!",
            "post_type": "post",
            "post_url": "http://localhost:8000/hello-world"
          }
        },
        {
          "id": "zombie:5",
          "score": 0.48280594,
          "data": {
            "ID": 5,
            "post_content": "",
            "post_date": "2025-06-13T12:44:46",
            "post_date_gmt": "2025-06-13T12:44:46",
            "post_excerpt": "",
            "post_modified": "2025-06-13T12:44:46",
            "post_modified_gmt": "2025-06-13T12:44:46",
            "post_name": "zombie-2",
            "post_status": "publish",
            "post_title": "Zombie-2",
            "post_type": "zombie",
            "post_url": "http://localhost:8000/zombie/zombie-2"
          }
        }
      ]
    }
  }
}

Using filters

Section titled “Using filters”

The client can also filter documents based on a provided query string — for example, excluding the rabbit post type.

query FindNearestDocumentWithFilter {
  similarity(
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
      filter: "NOT post_type:rabbit"
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

Sample response:

{
  "data": {
    "similarity": {
      "total": 0,
      "docs": [
        {
          "id": "horse:7",
          "score": 2.2204816,
          "data": {
            "ID": 1,
            "post_content": "Horse in a field",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "Greg the horse",
            "post_type": "horse"
          }
        }
      ]
    }
  }
}

Pagination

Section titled “Pagination”

The similarity API allows you to paginate through results. The following query would offset to the 10th document and then display the next five additional documents.

query FindNearestDocumentWithPagination {
  similarity(
    limit: 5
    offset: 10
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
      filter: "NOT post_type:rabbit"
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

Minimum score

Section titled “Minimum score”

The similarity API also allows you to set a min score, since the nearest documents are based on probability the client can set a minimum score threshold to omit documents that fall below the threshold.

query FindNearestDocumentWithMinScore {
  similarity(
    minScore: 0.8
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}