Skip to main content
POST
curl
This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).
With an API key, you can only create the types of suggestion that come from user actions, and the request must say who created it with creation. If a matching active suggestion already exists, its lifetime isn’t changed. Required ACL: editSettings

Authorizations

x-algolia-application-id
string
header
required

Your Algolia application ID.

x-algolia-api-key
string
header
required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Body

application/json
target
object
required
type
enum<string>
required

Registered definition from which the service derives the suggestion's description and options.

Available options:
SUGGESTION_TYPE_UNSPECIFIED,
ACTIVATE_DYNAMIC_RE_RANKING,
ACTIVATE_PERSONALIZATION,
ACTIVATE_NEURAL_SEARCH,
ACTIVATE_ADVANCED_PERSONALIZATION,
UPDATE_INDEX_SETTINGS
completion
object

Creates the suggestion already completed.

creation
object

Who created the suggestion and from where. Required when you use an API key.

description
string

Description of the suggestion.

Required string length: 1 - 1000
metadata
object

Context to store with the suggestion. The service doesn't interpret it.

payload
object

The change the suggestion makes, in the payload format of its type.

provenance
object

Required unless the suggestion is created already completed.

title
string

Title of the suggestion.

Required string length: 1 - 200
validFor
string

How long the new suggestion stays active, as a number of seconds followed by s. The service default applies when omitted. It must not exceed the service maximum. It doesn't change a matching active suggestion.

Example:

"3600s"

Response

OK

A recommended action for an application or an index.

abTest
object
adoptionDetectedAt
string<date-time>

Date and time in RFC 3339 format.

Example:

"2026-11-09T10:17:47Z"

completion
object

Set once the suggestion is completed, whoever completed it.

createdAt
string<date-time>

Date and time in RFC 3339 format.

Example:

"2026-11-09T10:17:47Z"

creation
object
description
string

Description of the suggestion.

directAdoption
object
dismissedAt
string<date-time>

Set when the userId passed to the list request dismissed this suggestion within the dismissal cooldown.

Example:

"2026-11-09T10:17:47Z"

expiresAt
string<date-time>

Date and time in RFC 3339 format.

Example:

"2026-11-09T10:17:47Z"

id
string

Unique identifier of the suggestion.

metadata
object

Context the creator stored with the suggestion. The service doesn't interpret it.

payload
object

The change the suggestion makes, in the payload format of its type.

provenance
object

Where the evidence for the suggestion comes from.

state
enum<string>

Lifecycle state of the suggestion.

Available options:
SUGGESTION_STATE_UNSPECIFIED,
ACTIVE,
EXPIRED,
WITHDRAWN,
COMPLETED
target
object
title
string

Title of the suggestion.

type
enum<string>

Registered definition from which the service derives the suggestion's description and options.

Available options:
SUGGESTION_TYPE_UNSPECIFIED,
ACTIVATE_DYNAMIC_RE_RANKING,
ACTIVATE_PERSONALIZATION,
ACTIVATE_NEURAL_SEARCH,
ACTIVATE_ADVANCED_PERSONALIZATION,
UPDATE_INDEX_SETTINGS
withdrawnAt
string<date-time>

Date and time in RFC 3339 format.

Example:

"2026-11-09T10:17:47Z"

Last modified on November 17, 2026