Algolia acquires Search.io » 

Read More
Search.io
Documentation Powered by Redocly

Search.io API (4.0.0)

Download OpenAPI specification:Download

API Support: support@search.io URL: https://www.search.io/company/contact Terms of Service

Search.io offers a search and discovery service with Neuralsearch®, the world's first instant AI search technology. Businesses of all sizes use Search.io to build site search and discovery solutions that maximize e-commerce revenue, optimize on-site customer experience, and scale their online presence.

Read more about the Search.io API

Authentication

BasicAuth

The Search.io API uses API keys to authenticate requests.

You should provide either your account's API key or your collection's API key. The type of key you provide depends on the required level of access for the request you are making. To administer your account (e.g. create and delete collections) you should provide an account key. For most other requests (e.g. query collection) you should provide a collection key.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key ID as the basic auth username value. Provide your API key secret as the basic auth password value.

$ curl https://api.search.io -u <key_id>:<key_secret>

You can find your account's API keys in the Search.io Console account credentials page. You can find your collection's API keys in the Search.io Console collection credentials page.

All API requests must be made over HTTPS. Calls made over plain HTTP fail. API requests without authentication also fail.

For customers in Australia and New Zealand, use the https://au-api.search.io endpoint for faster routing to collections based in the au region.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Rate limiting

The Search.io API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession may see error responses that show up as HTTP status code 429.

For the UpsertRecord call, Search.io allows up to 175 write operations per second.

Treat these limits as maximums and don't generate unnecessary load. See Handling limiting gracefully for advice on handling 429s.

We may reduce limits to prevent abuse.

Common causes and mitigations

Rate limiting can occur under a variety of conditions, but it's most common in these scenarios:

  • Running a large volume of closely-spaced requests. Often this is part of a user's long-running reindex job. When engaging in these activities, you should try to control the request rate (see Handling limiting gracefully).
  • Running batch operations in parallel. Often BatchUpsertRecords is used as part of a user's long-running reindex job. A batch of records of size N passed to BatchUpsertRecords is counted as N UpsertRecord calls for the purposes of rate limiting, as opposed to a single call. Treat batch API calls as a convenience rather than a way to get more write throughput.

Handling limiting gracefully

A basic technique for integrations to gracefully handle limiting is to watch for 429 HTTP status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.

Collections

Collections store the records that you want to search through.

They also contain the configuration associated with your data including pipelines, rules, synonyms, authorized domains and analytics. Each collection has an associated schema that designates field names, field types, and whether a field's data is indexed for text search.

Create a collection for every new set of related records that you want to search through.

List collections

Retrieve a list of collections in an account.

query Parameters
page_size
integer <int32>

The maximum number of collections to return. The service may return fewer than this value.

If unspecified, at most 50 collections are returned.

The maximum value is 100; values above 100 are coerced to 100.

page_token
string

A page token, received from a previous ListCollections call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListCollections must match the call that provided the page token.

view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in each retrieved collection.

  • BASIC: Include basic information including display name and domains. This is the default value (for both ListCollections and GetCollection).
  • FULL: Include the information from BASIC, plus full collection details like disk usage.
header Parameters
Account-Id
string

The account that owns this set of collections, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "next_page_token": "string"
}

Create collection

Create an empty collection.

Before records can be added to a collection, the schema and pipelines for the collection have to be set up. Consider setting up new collections via the Search.io Console, which handles the creation of the schema and pipelines for you.

query Parameters
collection_id
required
string

The ID to use for the collection.

This must start with an alphanumeric character followed by one or more alphanumeric or - characters. Strictly speaking, it must match the regular expression: ^[A-Za-z][A-Za-z0-9\-]*$.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

Details of the collection to create.

authorized_query_domains
Array of strings

The list of authorized query domains for the collection.

Client-side / browser requests to the QueryCollection call can be made by any authorized query domain or any of its subdomains. This allows your interface to make search requests without having to provide an API key in the client-side request.

display_name
required
string

The collection's display name. You can change this at any time.

Responses

Request samples

Content type
application/json
{
  • "authorized_query_domains": [
    ],
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "string"
}

Delete collection

Delete a collection and all of its associated data.

Note: This operation cannot be reversed.

path Parameters
collection_id
required
string

The collection to delete, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
null

Get collection

Retrieve the details of a collection.

path Parameters
collection_id
required
string

The collection to retrieve, e.g. my-collection.

query Parameters
view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in the retrieved pipeline.

  • BASIC: Include basic information including display name and domains. This is the default value (for both ListCollections and GetCollection).
  • FULL: Include the information from BASIC, plus full collection details like disk usage.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "string"
}

Update collection

Update the details of a collection.

path Parameters
collection_id
required
string

The collection to update, e.g. my-collection.

query Parameters
update_mask
string

The list of fields to update, separated by a comma, e.g. authorized_query_domains,display_name.

Each field should be in snake case.

For each field that you want to update, provide a corresponding value in the collection object containing the new value.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The details of the collection to update.

authorized_query_domains
Array of strings

The list of authorized query domains for the collection.

Client-side / browser requests to the QueryCollection call can be made by any authorized query domain or any of its subdomains. This allows your interface to make search requests without having to provide an API key in the client-side request.

display_name
required
string

The collection's display name. You can change this at any time.

Responses

Request samples

Content type
application/json
{
  • "authorized_query_domains": [
    ],
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "string"
}

Experiment

Run a query on a collection with a hypothetical configuration to see what kinds of results it produces.

Saved promotions with a start date in the future are enabled during the experiment, unless they are explicitly disabled.

The following example demonstrates how to run a simple experiment for a string, against a pipeline and with a proposed promotion:

{
  "pipeline": { "name": "my-pipeline" },
  "variables": { "q": "search terms" },
  "promotions": [{
    "id": "1234",
    "condition": "q = 'search terms'",
    "pins": [{
      "key": { "field": "id", "value": "54hdc7h2334h" },
      "position": 1
    }]
  }]
}
path Parameters
collection_id
required
string

The collection to query, e.g. my-collection.

Request Body schema: application/json
object (Pipeline)
object (ExperimentRequestPipeline)

The pipeline to use when running the experiment.

If not provided the default query pipeline is used.

Array of objects (Promotion)

The promotions to consider active when running the search.

Provided promotions override existing promotions with the same ID.

required
object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

The most important variable is q which is the query the user entered, for example:

{ "q": "search terms" }

To paginate through results, set the variables page and resultsPerPage, for example:

{ "q": "search terms", "page": 5, "resultsPerPage": 20 }

To sort results, set the variable sort to the name of one of your collection's schema fields, for example:

{ "q": "search terms", "sort": "name" }

To sort in reverse, prefix the schema field with a minus sign -, for example:

{ "q": "search terms", "sort": "-name" }

Responses

Request samples

Content type
application/json
{
  • "custom_pipeline": {
    },
  • "pipeline": {
    },
  • "promotions": [
    ],
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "query_response": {
    }
}

Query collection

Query the collection to search for records.

The following example demonstrates how to run a simple search for a particular string:

{
  "variables": { "q": "search terms" }
}

For more information:

Note: Unlike other API calls, the QueryCollection call can be called from a browser. When called from a browser, the Account-Id header must be set to your account ID.

path Parameters
collection_id
required
string

The collection to query, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Unlike other API calls, the QueryCollection call can be called from a browser. When called from a browser, the Account-Id header must be set to your account ID.

Request Body schema: application/json
object (QueryCollectionRequestPipeline)

The pipeline to use when querying the collection.

If not provided the default query pipeline is used.

object (QueryCollectionRequestTracking)
required
object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

The most important variable is q which is the query the user entered, for example:

{ "q": "search terms" }

To paginate through results, set the variables page and resultsPerPage, for example:

{ "q": "search terms", "page": 5, "resultsPerPage": 20 }

To sort results, set the variable sort to the name of one of your collection's schema fields, for example:

{ "q": "search terms", "sort": "name" }

To sort in reverse, prefix the schema field with a minus sign -, for example:

{ "q": "search terms", "sort": "-name" }

Responses

Request samples

Content type
application/json
{
  • "pipeline": {
    },
  • "tracking": {
    },
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "active_promotions": [
    ],
  • "aggregate_filters": {
    },
  • "aggregates": {
    },
  • "banners": [
    ],
  • "feature_score_weight": 0,
  • "pipeline": {
    },
  • "processing_duration": "string",
  • "query_id": "string",
  • "redirects": {
    },
  • "results": [
    ],
  • "total_size": "string",
  • "variables": {
    }
}

Query collection Deprecated

Query the collection to search for records.

The following example demonstrates how to run a simple search for a particular string:

{
  "variables": { "q": "search terms" }
}

For more information:

Note: Unlike other API calls, the QueryCollection call can be called from a browser. When called from a browser, the Account-Id header must be set to your account ID.

path Parameters
collection_id
required
string

The collection to query, e.g. my-collection.

Request Body schema: application/json
object (QueryCollectionRequestPipeline)

The pipeline to use when querying the collection.

If not provided the default query pipeline is used.

object (QueryCollectionRequestTracking)
required
object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

The most important variable is q which is the query the user entered, for example:

{ "q": "search terms" }

To paginate through results, set the variables page and resultsPerPage, for example:

{ "q": "search terms", "page": 5, "resultsPerPage": 20 }

To sort results, set the variable sort to the name of one of your collection's schema fields, for example:

{ "q": "search terms", "sort": "name" }

To sort in reverse, prefix the schema field with a minus sign -, for example:

{ "q": "search terms", "sort": "-name" }

Responses

Request samples

Content type
application/json
{
  • "pipeline": {
    },
  • "tracking": {
    },
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "active_promotions": [
    ],
  • "aggregate_filters": {
    },
  • "aggregates": {
    },
  • "banners": [
    ],
  • "feature_score_weight": 0,
  • "pipeline": {
    },
  • "processing_duration": "string",
  • "query_id": "string",
  • "redirects": {
    },
  • "results": [
    ],
  • "total_size": "string",
  • "variables": {
    }
}

Track event

Track an analytics event when a user interacts with an object returned by a QueryCollection request.

An analytics event can be tracked for the following objects:

  • Results
  • Promotion banners
  • Redirects

When tracking redirect events, set type to redirect.

  • Note: You must pass an Account-Id header.
  • Note: One of result_id, banner_id or redirect_id are required.
Read our guide on how to implement tracking using this API method.
path Parameters
collection_id
required
string

The collection to track the event against, e.g. my-collection.

header Parameters
Account-Id
required
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The details of the event to track.

banner_id
string

The identifier of the promotion banner the event is about.

object

An object made up of field-value pairs that contains additional metadata to record with the event.

query_id
required
string

The query identifier.

redirect_id
string

The identifier of the redirect the event is about.

result_id
string

The identifier of the result the event is about.

type
required
string

The type of event, e.g. click, redirect, purchase, add_to_cart.

Responses

Request samples

Content type
application/json
{
  • "banner_id": "string",
  • "metadata": {
    },
  • "query_id": "string",
  • "redirect_id": "string",
  • "result_id": "string",
  • "type": "string"
}

Response samples

Content type
application/json
{ }

Pipelines

In Search.io, you configure your search algorithm using pipelines.

Pipelines are easily configurable YAML-based scripts that define a series of steps that are executed sequentially when indexing a record, using a record pipeline, or performing a query, using a query pipeline.

List pipelines

Retrieve a list of pipelines in a collection.

path Parameters
collection_id
required
string

The collection that owns this set of pipelines, e.g. my-collection.

query Parameters
page_size
integer <int32>

The maximum number of pipelines to return. The service may return fewer than this value.

If unspecified, at most 50 pipelines are returned.

The maximum value is 1000; values above 1000 are coerced to 1000.

page_token
string

A page token, received from a previous ListPipelines call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListPipelines must match the call that provided the page token.

view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in each retrieved pipeline.

  • BASIC: Include basic information including type, name, version and description but not the full step configuration. This is the default value (for both ListPipelines and GetPipeline).
  • FULL: Include the information from BASIC, plus full step configuration.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "pipelines": [
    ]
}

Create pipeline

Create a new pipeline.

Pipelines are immutable once created. If you want to change a pipeline e.g. to add or change some steps, you need to create a new version of that pipeline.

To start using a new pipeline you need to update your record ingestion calls and/or your query calls to specify the new pipeline.

To create the pipeline from YAML, set the request's Content-Type header to application/yaml and submit the pipeline's YAML in the request body.

path Parameters
collection_id
required
string

The collection to create the pipeline in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema:

The pipeline to create.

description
string

Description of the pipeline.

name
required
string

The pipeline's name.

Must start with an alphanumeric character followed by one or more alphanumeric, _, - or . characters. Strictly speaking, it must match the regular expression: ^[a-zA-Z0-9][a-zA-Z0-9_\-\.]+$.

Array of objects (PipelineStep)

The post-steps that are run after an indexing operation or query request has been sent to the search index.

For indexing operations, the post-steps only run when creating new records. They do not run when updating records.

For querying, the post-steps have access to the result-set. This makes it possible to act on the results before sending them back to the caller.

Array of objects (PipelineStep)

The pre-steps that are run before an indexing operation or query request is sent to the search index.

type
required
string (PipelineType)
Default: "TYPE_UNSPECIFIED"
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"
  • RECORD: Record pipeline.
  • QUERY: Query pipeline.
version
required
string

The pipeline's version.

Must start with an alphanumeric character followed by one or more alphanumeric, _, - or . characters. Strictly speaking, it must match the regular expression: ^[a-zA-Z0-9][a-zA-Z0-9_\-\.]+$.

Responses

Request samples

Content type
{
  • "description": "string",
  • "name": "string",
  • "post_steps": [
    ],
  • "pre_steps": [
    ],
  • "type": "TYPE_UNSPECIFIED",
  • "version": "string"
}

Response samples

Content type
{
  • "collection_default": true,
  • "create_time": "2019-08-24T14:15:22Z",
  • "default_version": true,
  • "description": "string",
  • "name": "string",
  • "post_steps": [
    ],
  • "pre_steps": [
    ],
  • "type": "TYPE_UNSPECIFIED",
  • "version": "string"
}

Get pipeline

Retrieve the details of a pipeline. Supply the type, name and version.

To retrieve the pipeline in YAML, set the request's Accept header to application/yaml.

path Parameters
collection_id
required
string

The collection that owns the pipeline, e.g. my-collection.

type
required
string
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"

The type of the pipeline to retrieve.

name
required
string

The name of the pipeline to retrieve, e.g. my-pipeline.

version
required
string

The version of the pipeline to retrieve, e.g. 42.

query Parameters
view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in the retrieved pipeline.

  • BASIC: Include basic information including type, name, version and description but not the full step configuration. This is the default value (for both ListPipelines and GetPipeline).
  • FULL: Include the information from BASIC, plus full step configuration.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
{
  • "collection_default": true,
  • "create_time": "2019-08-24T14:15:22Z",
  • "default_version": true,
  • "description": "string",
  • "name": "string",
  • "post_steps": [
    ],
  • "pre_steps": [
    ],
  • "type": "TYPE_UNSPECIFIED",
  • "version": "string"
}

Get default pipeline version

Get the default version for a given pipeline.

The default version of a pipeline is used when a pipeline is referred to without specifying a version.

This allows you to change the pipeline version used for requests without having to change your code.

To retrieve the pipeline in YAML, set the request's Accept header to application/yaml.

path Parameters
collection_id
required
string

The collection that owns the pipeline to get the default version of, e.g. my-collection.

type
required
string
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"

The type of the pipeline to get the default version of.

name
required
string

The name of the pipeline to get the default version of, e.g. my-pipeline.

query Parameters
view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in the retrieved pipeline.

  • BASIC: Include basic information including type, name, version and description but not the full step configuration. This is the default value (for both ListPipelines and GetPipeline).
  • FULL: Include the information from BASIC, plus full step configuration.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
{
  • "collection_default": true,
  • "create_time": "2019-08-24T14:15:22Z",
  • "default_version": true,
  • "description": "string",
  • "name": "string",
  • "post_steps": [
    ],
  • "pre_steps": [
    ],
  • "type": "TYPE_UNSPECIFIED",
  • "version": "string"
}

Set default pipeline version

Set the default version for a given pipeline.

The default version of a pipeline is used when a pipeline is referred to without specifying a version.

This allows you to change the pipeline version used for requests without having to change your code.

path Parameters
collection_id
required
string

The collection that owns the pipeline to set the default version of, e.g. my-collection.

type
required
string
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"

The type of the pipeline to set the default version of.

name
required
string

The name of the pipeline to set the default version of, e.g. my-pipeline.

Request Body schema: application/json
version
required
string

The version to use as a default for this pipeline, e.g. 42.

Responses

Request samples

Content type
application/json
{
  • "version": "string"
}

Response samples

Content type
application/json
{ }

Generate pipelines

Generate basic record, query and autocomplete pipeline templates. Use these templates as a starting point for your collection's pipelines.

This call returns a set of pipelines that you can pass directly to the create pipeline call.

The generated templates can be returned in JSON, the default, or YAML. To return the generated pipelines in YAML, set the request's Accept header to application/yaml. The three pipelines in the YAML response are separated by three dashes (---).

path Parameters
collection_id
required
string

The collection, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
query_training_fields
Array of strings

A list of fields to train query suggestions from.

searchable_fields
required
Array of strings

A prioritized list of fields to search.

Responses

Request samples

Content type
application/json
{
  • "query_training_fields": [
    ],
  • "searchable_fields": [
    ]
}

Response samples

Content type
{
  • "autocomplete_pipeline": {
    },
  • "query_pipeline": {
    },
  • "record_pipeline": {
    }
}

Get default pipeline

Get the default pipeline for a collection.

Every collection has a default record pipeline and a default query pipeline.

When a pipeline is required to complete an operation, it can be omitted from the request if a default pipeline has been set. When adding a record to a collection, the default record pipeline is used if none is provided. When querying a collection, the default query pipeline is used if none is provided.

path Parameters
collection_id
required
string

The collection to get the default query pipeline of, e.g. my-collection.

query Parameters
type
required
string
Default: "TYPE_UNSPECIFIED"
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"

The type of the pipeline to get.

  • RECORD: Record pipeline.
  • QUERY: Query pipeline.

Responses

Response samples

Content type
application/json
{
  • "pipeline": "string"
}

Set default pipeline

Set the default pipeline for a collection.

Every collection has a default record pipeline and a default query pipeline.

When a pipeline is required to complete an operation, it can be omitted from the request if a default pipeline has been set. When adding a record to a collection, the default record pipeline is used if none is provided. When querying a collection, the default query pipeline is used if none is provided.

Once a default pipeline has been set it cannot be cleared, only set to another pipeline.

path Parameters
collection_id
required
string

The collection to set the default query pipeline of, e.g. my-collection.

Request Body schema: application/json
pipeline
required
string

The name of the pipeline to use when not otherwise specified.

type
required
string (PipelineType)
Default: "TYPE_UNSPECIFIED"
Enum: "TYPE_UNSPECIFIED" "RECORD" "QUERY"
  • RECORD: Record pipeline.
  • QUERY: Query pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipeline": "string",
  • "type": "TYPE_UNSPECIFIED"
}

Response samples

Content type
application/json
{ }

Schema

A schema describes the set of fields that records in a collection can have.

It is made up of a list of schema fields. Each schema field has a name, associated data type and mode.

For example, the following record:

{
  "id": "54hdc7h2334h",
  "name": "Smart TV",
  "price": 1999,
  "brand": "Acme",
  "in_stock": true,
  "tags": ["TV", "Smart TV"],
  "create_time": "2006-01-02T15:04:05Z07:00"
}

Requires the following schema fields:

  • id, of type STRING and mode UNIQUE
  • name, of type STRING
  • price, of type FLOAT
  • brand, of type STRING
  • in_stock, of type BOOLEAN
  • tags, of type array of STRING
  • create_time, of type TIMESTAMP

Type can be one of the following:

  • STRING
  • INTEGER
  • BOOLEAN
  • FLOAT
  • DOUBLE
  • TIMESTAMP, in RFC3339 format
  • BYTES
  • Array of STRING
  • Array of INTEGER
  • Array of BOOLEAN
  • Array of FLOAT
  • Array of DOUBLE
  • Array of TIMESTAMP

Mode can be one of the following:

  • NULLABLE, indicates a record field-value pair can be null
  • REQUIRED, indicates a record field-value pair is required
  • UNIQUE, indicates a record field-value pair must be unique across all records in the collection

List schema fields

Retrieve a list of schema fields in a collection.

path Parameters
collection_id
required
string

The collection that owns this set of schema fields, e.g. my-collection.

query Parameters
page_size
integer <int32>

The maximum number of schema fields to return. The service may return fewer than this value.

If unspecified, at most 50 schema fields are returned.

The maximum value is 1000; values above 1000 are coerced to 1000.

page_token
string

A page token, received from a previous ListSchemaFields call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListSchemaFields must match the call that provided the page token.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "schema_fields": [
    ],
  • "total_size": 0
}

Create schema field

Create a new field in a collection's schema.

path Parameters
collection_id
required
string

The collection to create a schema field in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The schema field to create.

array
boolean

Array indicates if the field is an array of values.

For example, if type is string and array is true, then the field is an array of strings.

array_length
integer <int32>

The required length of the array, if array is true.

This allows you to enforce that an array contains an exact number of items.

For example, to store a 2x2 vector, you could set type to float, array to true and array_length to 4.

description
string

The description of the field.

mode
string (SchemaFieldMode)
Default: "MODE_UNSPECIFIED"
Enum: "MODE_UNSPECIFIED" "NULLABLE" "REQUIRED" "UNIQUE"

Mode is an enumeration of modes for a field. Mode is required and cannot be unspecified.

  • NULLABLE: Nullable fields do not need to be specified.
  • REQUIRED: Required fields must be specified and cannot be null.
  • UNIQUE: Unique fields must be specified and must be unique.
name
string

The name of the field.

type
string (SchemaFieldType)
Default: "TYPE_UNSPECIFIED"
Enum: "TYPE_UNSPECIFIED" "STRING" "INTEGER" "FLOAT" "DOUBLE" "BOOLEAN" "TIMESTAMP" "BYTES"

Type represents the underlying data type of the field. Type is required and cannot be unspecified.

  • STRING: String values.
  • INTEGER: Integer values (64-bit).
  • FLOAT: Floating point values (32-bit).
  • DOUBLE: Double floating point values (64-bit).
  • BOOLEAN: Boolean values.
  • TIMESTAMP: Timestamp values.
  • BYTES: Raw byte values.

Responses

Request samples

Content type
application/json
{
  • "array": true,
  • "array_length": 0,
  • "description": "string",
  • "mode": "MODE_UNSPECIFIED",
  • "name": "string",
  • "type": "TYPE_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "array": true,
  • "array_length": 0,
  • "description": "string",
  • "mode": "MODE_UNSPECIFIED",
  • "name": "string",
  • "type": "TYPE_UNSPECIFIED"
}

Delete schema field

Deleting a schema field removes it from all records within the collection, however, references to the schema field in pipelines are not removed.

Note: This operation cannot be reversed.

path Parameters
collection_id
required
string

The collection the schema field belongs to, e.g. my-collection.

schema_field_name
required
string

The name of the schema field to delete.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
null

Update schema field

Update the details of a schema field.

Only name and description can be updated.

path Parameters
collection_id
required
string

The collection the schema field belongs to, e.g. my-collection.

schema_field_name
required
string

The name of the schema field to update.

query Parameters
update_mask
string

The list of fields to update, separated by a comma, e.g. name,description.

Each field should be in snake case.

For each field that you want to update, provide a corresponding value in the schema field object containing the new value.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The schema field details to update.

array
boolean

Array indicates if the field is an array of values.

For example, if type is string and array is true, then the field is an array of strings.

array_length
integer <int32>

The required length of the array, if array is true.

This allows you to enforce that an array contains an exact number of items.

For example, to store a 2x2 vector, you could set type to float, array to true and array_length to 4.

description
string

The description of the field.

mode
string (SchemaFieldMode)
Default: "MODE_UNSPECIFIED"
Enum: "MODE_UNSPECIFIED" "NULLABLE" "REQUIRED" "UNIQUE"

Mode is an enumeration of modes for a field. Mode is required and cannot be unspecified.

  • NULLABLE: Nullable fields do not need to be specified.
  • REQUIRED: Required fields must be specified and cannot be null.
  • UNIQUE: Unique fields must be specified and must be unique.
name
string

The name of the field.

type
string (SchemaFieldType)
Default: "TYPE_UNSPECIFIED"
Enum: "TYPE_UNSPECIFIED" "STRING" "INTEGER" "FLOAT" "DOUBLE" "BOOLEAN" "TIMESTAMP" "BYTES"

Type represents the underlying data type of the field. Type is required and cannot be unspecified.

  • STRING: String values.
  • INTEGER: Integer values (64-bit).
  • FLOAT: Floating point values (32-bit).
  • DOUBLE: Double floating point values (64-bit).
  • BOOLEAN: Boolean values.
  • TIMESTAMP: Timestamp values.
  • BYTES: Raw byte values.

Responses

Request samples

Content type
application/json
{
  • "array": true,
  • "array_length": 0,
  • "description": "string",
  • "mode": "MODE_UNSPECIFIED",
  • "name": "string",
  • "type": "TYPE_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "array": true,
  • "array_length": 0,
  • "description": "string",
  • "mode": "MODE_UNSPECIFIED",
  • "name": "string",
  • "type": "TYPE_UNSPECIFIED"
}

Batch create schema fields

The batch version of the CreateSchemaField call.

path Parameters
collection_id
required
string

The collection to create the schema fields in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
Array of objects (SchemaField)

A list of fields to create.

A maximum of 1000 fields can be created in a batch.

Responses

Request samples

Content type
application/json
{
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "fields": [
    ]
}

Records

A record is a single entry in a collection, made up of field-value pairs.

For example in the following record:

{
  "name": "Kim Jones"
}

There is one field-value pair. The field is name and the value is "Kim Jones".

Records are analogous to rows in a database. Records can represent:

  • Webpages
  • Standard documents e.g. HTML, PDF, Microsoft Word Document
  • Custom data objects, if your data is not webpages or documents

The set of fields a record can have is known as its schema. Webpages indexed via Search.io's web crawler have a predefined schema that can be extended with custom fields. For custom records, you can define your own schema.

Batch update records

The batch version of the UpdateRecord call.

You cannot run batches in parallel. Your code must wait for previous calls to BatchUpdateRecords to complete before making subsequent calls.

A maximum of 200 records can be updated in a batch.

path Parameters
collection_id
required
string

The collection that contains the records to update, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
required
Array of objects (UpdateRecordRequest)

The list of requests containing the records to be updated.

A maximum of 200 records can be updated in a batch.

update_mask
string

The list of fields to be updated, separated by a comma, e.g. field1,field2.

For each field that you want to update, provide a corresponding value in each record object, within the requests list, containing the new value.

If provided, and you also provide an update mask in any child request, the values must match.

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ],
  • "update_mask": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "records": [
    ]
}

Batch upsert records

The batch version of the UpsertRecord call.

You cannot run batches in parallel. Your code must wait for previous calls to BatchUpsertRecords to complete before making subsequent calls.

A maximum of 200 records can be upserted in a batch.

path Parameters
collection_id
required
string

The collection to upsert the records in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
object (BatchUpsertRecordsRequestPipeline)

The pipeline to use when upserting the records.

If not provided the default record pipeline is used.

records
required
Array of objects

A list of records to upsert.

A maximum of 200 records can be upserted in a batch.

object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

Responses

Request samples

Content type
application/json
{
  • "pipeline": {
    },
  • "records": [
    ],
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "keys": [
    ],
  • "variables": [
    ]
}

Delete record

Delete a record with the given key.

If you receive "service unavailable" errors, the collection may be in read only mode. This is indicated by a COLLECTION_READ_ONLY reason inside the error details. The following snippet shows the JSON response for a collection read only error.

{
  "code": 14,
  "message": "read only",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "COLLECTION_READ_ONLY"
    }
  ]
}

If you encounter this error you should retry your call. Your app can use the Retry-After HTTP header to know when to retry.

path Parameters
collection_id
required
string

The collection that contains the record to delete, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
required
object (RecordKey)

Responses

Request samples

Content type
application/json
{
  • "key": {
    }
}

Response samples

Content type
application/json
null

Get record

Retrieve a record with the given key.

path Parameters
collection_id
required
string

The collection that contains the record to retrieve, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
required
object (RecordKey)

Responses

Request samples

Content type
application/json
{
  • "key": {
    }
}

Response samples

Content type
application/json
{ }

Update record

Add or update specific fields within a record with the given values. The updated record is returned in the response.

To replace all fields in a record, you should use the UpsertRecord call.

Note that the update record call cannot be used to add or update indexed or unique fields. For this case use the UpsertRecord call.

If you receive "service unavailable" errors, the collection may be in read only mode. This is indicated by a COLLECTION_READ_ONLY reason inside the error details. The following snippet shows the JSON response for a collection read only error.

{
  "code": 14,
  "message": "read only",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "COLLECTION_READ_ONLY"
    }
  ]
}

If you encounter this error you should retry your call. Your app can use the Retry-After HTTP header to know when to retry.

path Parameters
collection_id
required
string

The collection that contains the record to update, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
required
object (RecordKey)
required
object

The record to update.

update_mask
required
string

The list of fields to be updated, separated by a comma, e.g. field1,field2.

For each field that you want to update, provide a corresponding value in the record object containing the new value.

Responses

Request samples

Content type
application/json
{
  • "key": {
    },
  • "record": {
    },
  • "update_mask": "string"
}

Response samples

Content type
application/json
{ }

Upsert record

If the record does not exist in the collection it is inserted. If it does exist it is updated.

If no pipeline is specified, the default record pipeline is used to process the record.

If the record is inserted, the response contains the key of the inserted record. You can use this if you need to retrieve or delete the record. If the record is updated, the response does not contain a key. Callers can use this as a signal to determine if the record is inserted/created or updated.

For example, to add a single product from your ecommerce store to a collection, use the following call:

{
  "pipeline": {
    "name": "my-pipeline",
    "version": "1"
  },
  "record": {
    "id": "54hdc7h2334h",
    "name": "Smart TV",
    "price": 1999,
    "brand": "Acme",
    "description": "...",
    "in_stock": true
  }
}

If you receive "service unavailable" errors, the collection may be in read only mode. This is indicated by a COLLECTION_READ_ONLY reason inside the error details. The following snippet shows the JSON response for a collection read only error.

{
  "code": 14,
  "message": "read only",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "COLLECTION_READ_ONLY"
    }
  ]
}

If you encounter this error you should retry your call. Your app can use the Retry-After HTTP header to know when to retry.

path Parameters
collection_id
required
string

The collection to upsert the record in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
object (UpsertRecordRequestPipeline)

The pipeline to use when upserting the record.

If not provided the default record pipeline is used.

record
required
object

An object made up of field-value pairs that contains the record data.

object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

Responses

Request samples

Content type
application/json
{
  • "pipeline": {
    },
  • "record": { },
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "key": {
    },
  • "variables": {
    }
}

Promotions

List promotions

Retrieve a list of promotions in a collection.

Promotion pins, exclusions and filter boosts are not returned in this call.

path Parameters
collection_id
required
string

The collection that owns this set of promotions, e.g. my-collection.

query Parameters
page_size
integer <int32>

The maximum number of promotions to return. The service may return fewer than this value.

If unspecified, at most 50 promotions are returned.

The maximum value is 1000; values above 1000 are coerced to 1000.

page_token
string

A page token, received from a previous ListPromotions call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListPromotions must match the call that provided the page token.

view
string
Default: "PROMOTION_VIEW_UNSPECIFIED"
Enum: "PROMOTION_VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in each retrieved promotion.

  • BASIC: Include basic information including name, start time and end time, but not detailed information about the promotion effects.
  • FULL: Returns all information about a promotion. This is the default value.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "promotions": [
    ]
}

Create promotion

Create a new promotion in a collection.

path Parameters
collection_id
required
string

The collection to create a promotion in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The promotion to create.

Array of objects (Banner)

The banners that are injected into the result set when the promotion is triggered.

condition
required
string

A condition expression applied to a search request that determines which searches the promotion is active for.

For example, to apply the promotion's pins and boosts whenever a user searches for 'shoes' set condition to q = 'shoes'.

disabled
boolean

If disabled, the promotion is never triggered.

display_name
required
string

The promotion's display name.

end_time
string <date-time>

If specified, the promotion is considered disabled after this time.

Array of objects (PromotionExclusion)

The records to exclude from search results, if the promotion is enabled.

Array of objects (PromotionFilterBoost)

The filter boosts to apply to searches, if the promotion is enabled.

Array of objects (PromotionFilterCondition)

The conditions applied to the filters passed from the user. A query must match at least one of these in order to trigger the promotion. A filter condition is comprised of a set of filters of the form field = value and matches a query if all of those filters are present in the query.

For example, a query with the filter productType = 'shirt' AND size = 'medium' triggers a promotion with the filter condition productType = 'shirt', but not one with both productType = 'shirt', and size = 'small'`.

id
string

The promotion's ID.

Array of objects (PromotionPin)

The items to fix to specific positions in the search results.

Array of objects (PromotionRangeBoost)

The range boosts to apply to searches, if the promotion is enabled.

start_time
string <date-time>

If specified, the promotion is considered disabled before this time.

Responses

Request samples

Content type
application/json
{
  • "banners": [
    ],
  • "condition": "string",
  • "disabled": true,
  • "display_name": "string",
  • "end_time": "2019-08-24T14:15:22Z",
  • "exclusions": [
    ],
  • "filter_boosts": [
    ],
  • "filter_conditions": [
    ],
  • "id": "string",
  • "pins": [
    ],
  • "range_boosts": [
    ],
  • "start_time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "banners": [
    ],
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "display_name": "string",
  • "end_time": "2019-08-24T14:15:22Z",
  • "exclusions": [
    ],
  • "filter_boosts": [
    ],
  • "filter_conditions": [
    ],
  • "id": "string",
  • "pins": [
    ],
  • "range_boosts": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z"
}

Delete promotion

Delete a promotion and all of its associated data.

Note: This operation cannot be reversed.

path Parameters
collection_id
required
string

The collection the promotion belongs to, e.g. my-collection.

promotion_id
required
string

The promotion to delete, e.g. 1234.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
null

Get promotion

Retrieve the details of a promotion.

path Parameters
collection_id
required
string

The collection that owns the promotion, e.g. my-collection.

promotion_id
required
string

The promotion to retrieve, e.g. 1234.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "banners": [
    ],
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "display_name": "string",
  • "end_time": "2019-08-24T14:15:22Z",
  • "exclusions": [
    ],
  • "filter_boosts": [
    ],
  • "filter_conditions": [
    ],
  • "id": "string",
  • "pins": [
    ],
  • "range_boosts": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z"
}

Update promotion

Update the details of a promotion.

Pass each field that you want to update in the request body. Also specify the name of each field that you want to update in the update_mask in the request URL query string. Separate multiple fields with a comma. Fields included in the request body, but not included in the field mask are not updated.

For example, to update the display_name and start_time fields, make a PATCH request to the URL:

/v4/collections/{collection_id}/promotions/{promotion_id}?update_mask=display_name,start_time

With the JSON body:

{
  "display_name": "new value",
  "start_time": "2006-01-02T15:04:05Z07:00",
  "end_time": "2006-01-02T15:04:05Z07:00"
}

Note: In this example end_time is not updated because it is not specified in the update_mask.

path Parameters
collection_id
required
string

The collection the promotion belongs to, e.g. my-collection.

promotion_id
required
string

The promotion to update, e.g. 1234.

query Parameters
update_mask
required
string

The list of fields to be updated, separated by a comma, e.g. field1,field2.

Each field should be in snake case, e.g. display_name, filter_boosts.

For each field that you want to update, provide a corresponding value in the promotion object containing the new value.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

Details of the promotion to update.

Array of objects (Banner)

The banners that are injected into the result set when the promotion is triggered.

condition
required
string

A condition expression applied to a search request that determines which searches the promotion is active for.

For example, to apply the promotion's pins and boosts whenever a user searches for 'shoes' set condition to q = 'shoes'.

disabled
boolean

If disabled, the promotion is never triggered.

display_name
required
string

The promotion's display name.

end_time
string <date-time>

If specified, the promotion is considered disabled after this time.

Array of objects (PromotionExclusion)

The records to exclude from search results, if the promotion is enabled.

Array of objects (PromotionFilterBoost)

The filter boosts to apply to searches, if the promotion is enabled.

Array of objects (PromotionFilterCondition)

The conditions applied to the filters passed from the user. A query must match at least one of these in order to trigger the promotion. A filter condition is comprised of a set of filters of the form field = value and matches a query if all of those filters are present in the query.

For example, a query with the filter productType = 'shirt' AND size = 'medium' triggers a promotion with the filter condition productType = 'shirt', but not one with both productType = 'shirt', and size = 'small'`.

id
string

The promotion's ID.

Array of objects (PromotionPin)

The items to fix to specific positions in the search results.

Array of objects (PromotionRangeBoost)

The range boosts to apply to searches, if the promotion is enabled.

start_time
string <date-time>

If specified, the promotion is considered disabled before this time.

Responses

Request samples

Content type
application/json
{
  • "banners": [
    ],
  • "condition": "string",
  • "disabled": true,
  • "display_name": "string",
  • "end_time": "2019-08-24T14:15:22Z",
  • "exclusions": [
    ],
  • "filter_boosts": [
    ],
  • "filter_conditions": [
    ],
  • "id": "string",
  • "pins": [
    ],
  • "range_boosts": [
    ],
  • "start_time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "banners": [
    ],
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "display_name": "string",
  • "end_time": "2019-08-24T14:15:22Z",
  • "exclusions": [
    ],
  • "filter_boosts": [
    ],
  • "filter_conditions": [
    ],
  • "id": "string",
  • "pins": [
    ],
  • "range_boosts": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z"
}

Redirects

Websites, e-commerce stores and apps often have dedicated landing pages for important product categories, brands, or other promotional purposes.

Instead of performing a search, Search.io has the ability to redirect users to these landing pages when a query matches certain criteria.

List redirects

Retrieve a list of redirects in a collection.

path Parameters
collection_id
required
string

The collection that owns this set of redirects, e.g. my-collection.

query Parameters
page_size
integer <int32>

The maximum number of redirects to return. The service may return fewer than this value.

If unspecified, at most 50 redirects are returned.

The maximum value is 1000; values above 1000 are coerced to 1000.

page_token
string

A page token, received from a previous ListRedirects call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListRedirects must match the call that provided the page token.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "redirects": [
    ]
}

Create redirect

Create a new redirect in a collection.

path Parameters
collection_id
required
string

The collection to create a redirect in, e.g. my-collection.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The redirect to create.

condition
required
string

A condition expression applied to a search request that determines whether a search is redirected.

For example, to redirect if the user's query is apples, set condition to q = 'apples'.

disabled
boolean

If disabled, the redirect is never triggered.

target
required
string

The target to redirect the user to if their query matches condition.

For searches performed in a browser, target is usually a URL but it can be any value that your integration can interpret as a redirect.

For example, for URLs that you need to resolve at runtime, target might be a URL template string. For apps, target might be a unique identifier used to send the user to the correct view.

Responses

Request samples

Content type
application/json
{
  • "condition": "string",
  • "disabled": true,
  • "target": "string"
}

Response samples

Content type
application/json
{
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "id": "string",
  • "target": "string",
  • "update_time": "2019-08-24T14:15:22Z"
}

Delete redirect

Delete a redirect and all of its associated data.

Note: This operation cannot be reversed.

path Parameters
collection_id
required
string

The collection the redirect belongs to, e.g. my-collection.

redirect_id
required
string

The redirect to delete, e.g. 1234.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
null

Get redirect

Retrieve the details of a redirect.

path Parameters
collection_id
required
string

The collection that owns the redirect, e.g. my-collection.

redirect_id
required
string

The redirect to retrieve, e.g. 1234.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "id": "string",
  • "target": "string",
  • "update_time": "2019-08-24T14:15:22Z"
}

Update redirect

Update the details of a redirect.

Pass each field that you want to update in the request body. Also specify the name of each field that you want to update in the update_mask in the request URL query string. Separate multiple fields with a comma. Fields included in the request body, but not included in the field mask are not updated.

For example, to update the condition field, make a PATCH request to the URL:

/v4/collections/{collection_id}/redirects/{redirect_id}?update_mask=condition

With the JSON body:

{
  "condition": "new value",
  "target": "..."
}

Note: In this example target is not updated because it is not specified in the update_mask.

path Parameters
collection_id
required
string

The collection the redirect belongs to, e.g. my-collection.

redirect_id
required
string

The redirect to update, e.g. 1234.

query Parameters
update_mask
required
string

The list of fields to be updated, separated by a comma, e.g. field1,field2.

Each field should be in snake case, e.g. condition, target.

For each field that you want to update, provide a corresponding value in the redirect object containing the new value.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

Details of the redirect to update.

condition
required
string

A condition expression applied to a search request that determines whether a search is redirected.

For example, to redirect if the user's query is apples, set condition to q = 'apples'.

disabled
boolean

If disabled, the redirect is never triggered.

target
required
string

The target to redirect the user to if their query matches condition.

For searches performed in a browser, target is usually a URL but it can be any value that your integration can interpret as a redirect.

For example, for URLs that you need to resolve at runtime, target might be a URL template string. For apps, target might be a unique identifier used to send the user to the correct view.

Responses

Request samples

Content type
application/json
{
  • "condition": "string",
  • "disabled": true,
  • "target": "string"
}

Response samples

Content type
application/json
{
  • "collection_id": "string",
  • "condition": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "id": "string",
  • "target": "string",
  • "update_time": "2019-08-24T14:15:22Z"
}

Events

Send event

Send an event to the ranking system after a user interacts with a search result.

When querying a collection, you can set the tracking type of the query request. When it is CLICK or POS_NEG, a token is generated for each result in the query response. You can use this token to provide feedback to the ranking system. Each time you want to record an event on a particular search result, use the send event call and provide:

  • The name of the event, e.g. click, redirect, purchase.
  • The token from the search result.
  • The weight to assign to the event, e.g. 1.
  • An object containing any additional metadata.

For example, to send an event where a customer purchased a product, use the following call:

{
  "name": "purchase",
  "token": "eyJ...",
  "weight": 1,
  "metadata": {
    "discount": 0.2,
    "margin": 30.0,
    "customer_id": "12345",
    "ui_test_segment": "A"
  }
}

When sending event tokens returned from redirects, set name to redirect.

Note: You must pass an Account-Id header.

header Parameters
Account-Id
required
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json
object

An object made up of field-value pairs that contains additional metadata to record with the event.

Every value in the object must be one of the following primitive types:

  • boolean
  • number
  • string
name
required
string

The name of event, e.g. click, redirect, purchase.

token
required
string

The token corresponding to the search result that was interacted with, e.g. eyJ....

weight
integer <int32>

The weight assigned to the event.

Generally a sensible weight is 1. If you want to weight an event in a certain way you can use a value other than 1. For example, if you want to capture profit in an event, you could set the weight to a value that represents the profit.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "name": "string",
  • "token": "string",
  • "weight": 0
}

Response samples

Content type
application/json
{ }

Send event Deprecated

Send an event to the ranking system after a user interacts with a search result.

When querying a collection, you can set the tracking type of the query request. When it is CLICK or POS_NEG, a token is generated for each result in the query response. You can use this token to provide feedback to the ranking system. Each time you want to record an event on a particular search result, use the send event call and provide:

  • The name of the event, e.g. click, redirect, purchase.
  • The token from the search result.
  • The weight to assign to the event, e.g. 1.
  • An object containing any additional metadata.

For example, to send an event where a customer purchased a product, use the following call:

{
  "name": "purchase",
  "token": "eyJ...",
  "weight": 1,
  "metadata": {
    "discount": 0.2,
    "margin": 30.0,
    "customer_id": "12345",
    "ui_test_segment": "A"
  }
}

When sending event tokens returned from redirects, set name to redirect.

Note: You must pass an Account-Id header.

Request Body schema: application/json
object

An object made up of field-value pairs that contains additional metadata to record with the event.

Every value in the object must be one of the following primitive types:

  • boolean
  • number
  • string
name
required
string

The name of event, e.g. click, redirect, purchase.

token
required
string

The token corresponding to the search result that was interacted with, e.g. eyJ....

weight
integer <int32>

The weight assigned to the event.

Generally a sensible weight is 1. If you want to weight an event in a certain way you can use a value other than 1. For example, if you want to capture profit in an event, you could set the weight to a value that represents the profit.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "name": "string",
  • "token": "string",
  • "weight": 0
}

Response samples

Content type
application/json
{ }