> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a suggestion

> Creates a suggestion of the given type for an application or an index.

This is a **beta feature** according to [Algolia's Terms of Service ("Beta Services")](https://www.algolia.com/policies/terms/).

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`


## OpenAPI

````yaml specs/suggested-actions.yml post /2/suggested-actions
openapi: 3.1.0
info:
  title: Suggested Actions API
  summary: >-
    The Suggested Actions API returns recommended actions that can improve your
    search
  description: >
    Suggested Actions are recommendations, such as turning on a feature, that
    can improve the search experience of an Algolia application.


    ## Base URLs


    Base URLs for the Suggested Actions API:


    - `https://sact.us.algolia.com`

    - `https://sact.eu.algolia.com`


    Use the URL that matches the region of your application.


    **All requests must use HTTPS.**


    ## Authentication


    Add these headers to authenticate requests:


    - `x-algolia-application-id`. Your Algolia application ID.

    - `x-algolia-api-key`. An API key with the necessary permissions to make the
    request.


    You can find your application ID and API key in the [Algolia
    dashboard](https://dashboard.algolia.com/account/api-keys).


    ## Response status and errors


    Response bodies are JSON objects.


    Successful responses return `2xx` statuses. Client errors return `4xx`
    statuses. Server errors return `5xx` statuses.

    Error responses have a `message` property with more information.


    ## Version


    The current version of the Suggested Actions API is version 2, indicated by
    the `/2/` in each endpoint's URL.
  version: 1.0.0
servers:
  - url: https://sact.{region}.algolia.com
    description: The region where your Algolia application is hosted.
    variables:
      region:
        description: The region where your Algolia application is hosted.
        enum:
          - us
          - eu
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: suggestions
    x-displayName: Suggestions
    description: Retrieve, create and dismiss suggested actions for an application.
paths:
  /2/suggested-actions:
    post:
      tags:
        - suggestions
      summary: Create a suggestion
      description: >
        Creates a suggestion of the given type for an application or an index.


        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.
      operationId: createSuggestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSuggestionParams'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/BadRequest-2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-codeSamples:
        - lang: javascript
          label: JavaScript
          source: >-
            // Initialize the client

            // Replace 'us' with your Algolia Application Region

            const client = suggestedActionsClient('ALGOLIA_APPLICATION_ID',
            'ALGOLIA_API_KEY', 'us');


            // Call the API

            const response = await client.createSuggestion({ type:
            'ACTIVATE_NEURAL_SEARCH', target: { appId: 'MY_APP_ID' } });



            // print the response

            console.log(response);
        - lang: cURL
          label: curl
          source: |-
            curl --request POST \
              --url https://sact.us.algolia.com/2/suggested-actions \
              --header 'accept: application/json' \
              --header 'content-type: application/json' \
              --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
              --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
              --data '
            {
              "type": "SUGGESTION_TYPE_UNSPECIFIED",
              "target": {
                "appId": "a",
                "index": "lorem"
              },
              "provenance": {
                "sources": [
                  {
                    "kind": "EVIDENCE_SOURCE_KIND_UNSPECIFIED",
                    "id": "lorem",
                    "version": "lorem",
                    "observedAt": "2026-11-09T10:17:47Z",
                    "evidence": {}
                  }
                ]
              },
              "validFor": "3600s",
              "title": "lorem",
              "description": "lorem",
              "payload": {},
              "completion": {
                "completedBy": "lorem",
                "source": "SOURCE_UNSPECIFIED",
                "completedAt": "2026-11-09T10:17:47Z"
              },
              "metadata": {},
              "creation": {
                "createdBy": "lorem",
                "source": "SOURCE_UNSPECIFIED"
              }
            }
            '
components:
  schemas:
    CreateSuggestionParams:
      type: object
      additionalProperties: false
      required:
        - type
        - target
      properties:
        target:
          $ref: '#/components/schemas/Target'
        type:
          $ref: '#/components/schemas/SuggestionType'
        completion:
          $ref: '#/components/schemas/Completion'
          description: Creates the suggestion already completed.
        creation:
          $ref: '#/components/schemas/Creation'
          description: >-
            Who created the suggestion and from where. Required when you use an
            API key.
        description:
          type: string
          minLength: 1
          maxLength: 1000
          description: Description of the suggestion.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Context to store with the suggestion. The service doesn't interpret
            it.
        payload:
          type: object
          additionalProperties: true
          description: The change the suggestion makes, in the payload format of its type.
        provenance:
          $ref: '#/components/schemas/Provenance'
          description: Required unless the suggestion is created already completed.
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Title of the suggestion.
        validFor:
          type: string
          description: >
            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
    Suggestion:
      type: object
      description: A recommended action for an application or an index.
      additionalProperties: false
      properties:
        abTest:
          $ref: '#/components/schemas/SuggestionOption'
        adoptionDetectedAt:
          $ref: '#/components/schemas/Timestamp'
        completion:
          $ref: '#/components/schemas/Completion'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        creation:
          $ref: '#/components/schemas/Creation'
        description:
          type: string
          description: Description of the suggestion.
        directAdoption:
          $ref: '#/components/schemas/SuggestionOption'
        dismissedAt:
          $ref: '#/components/schemas/Timestamp'
          description: >-
            Set when the `userId` passed to the list request dismissed this
            suggestion within the dismissal cooldown.
        expiresAt:
          $ref: '#/components/schemas/Timestamp'
        id:
          type: string
          description: Unique identifier of the suggestion.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Context the creator stored with the suggestion. The service doesn't
            interpret it.
        payload:
          type: object
          additionalProperties: true
          description: The change the suggestion makes, in the payload format of its type.
        provenance:
          $ref: '#/components/schemas/Provenance'
        state:
          $ref: '#/components/schemas/SuggestionState'
        target:
          $ref: '#/components/schemas/Target'
        title:
          type: string
          description: Title of the suggestion.
        type:
          $ref: '#/components/schemas/SuggestionType'
        withdrawnAt:
          $ref: '#/components/schemas/Timestamp'
    Target:
      type: object
      additionalProperties: false
      required:
        - appId
      properties:
        appId:
          type: string
          minLength: 1
          pattern: ^[a-zA-Z0-9_-]+$
          description: Algolia application ID the suggestion applies to.
        index:
          type: string
          minLength: 1
          description: Index the suggestion applies to, if it targets one index.
    SuggestionType:
      type: string
      description: >-
        Registered definition from which the service derives the suggestion's
        description and options.
      enum:
        - SUGGESTION_TYPE_UNSPECIFIED
        - ACTIVATE_DYNAMIC_RE_RANKING
        - ACTIVATE_PERSONALIZATION
        - ACTIVATE_NEURAL_SEARCH
        - ACTIVATE_ADVANCED_PERSONALIZATION
        - UPDATE_INDEX_SETTINGS
    Completion:
      type: object
      additionalProperties: false
      description: Set once the suggestion is completed, whoever completed it.
      properties:
        completedAt:
          $ref: '#/components/schemas/Timestamp'
        completedBy:
          type: string
          minLength: 1
          maxLength: 256
          description: |
            Who completed the suggestion, such as a dashboard user ID.
            Empty when the observer detected the adoption.
        source:
          $ref: '#/components/schemas/Source'
    Creation:
      type: object
      additionalProperties: false
      properties:
        createdBy:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            The caller's login, or the user's ID when a user's action created
            the suggestion.
        source:
          $ref: '#/components/schemas/Source'
    Provenance:
      type: object
      additionalProperties: false
      required:
        - sources
      description: Where the evidence for the suggestion comes from.
      properties:
        sources:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/EvidenceSource'
    SuggestionOption:
      type: object
      additionalProperties: false
      properties:
        guidedActionSequence:
          $ref: '#/components/schemas/GuidedActionSequence'
    Timestamp:
      type: string
      format: date-time
      description: Date and time in RFC 3339 format.
      example: '2026-11-09T10:17:47Z'
    SuggestionState:
      type: string
      description: Lifecycle state of the suggestion.
      enum:
        - SUGGESTION_STATE_UNSPECIFIED
        - ACTIVE
        - EXPIRED
        - WITHDRAWN
        - COMPLETED
    Error:
      type: object
      description: Error returned by the Suggested Actions API.
      required:
        - status
        - message
      properties:
        message:
          type: string
          description: Description of the error.
        status:
          type: integer
          description: HTTP status code.
    Source:
      type: string
      description: Who created or completed a suggestion.
      enum:
        - SOURCE_UNSPECIFIED
        - AUTOPILOT
        - ASSIST
        - DASHBOARD
        - OBSERVER
    EvidenceSource:
      type: object
      additionalProperties: false
      required:
        - kind
        - id
        - evidence
      properties:
        evidence:
          type: object
          additionalProperties: true
          description: Evidence that the source produced.
        id:
          type: string
          minLength: 1
          description: >
            Identifier of the specific source result, such as a feature
            qualifier or feature fit result ID.

            Together with `kind`, it identifies the evidence source.
        kind:
          $ref: '#/components/schemas/EvidenceSourceKind'
        observedAt:
          $ref: '#/components/schemas/Timestamp'
        version:
          type: string
          minLength: 1
          description: Version of the source.
    GuidedActionSequence:
      type: object
      additionalProperties: false
      properties:
        actions:
          type: array
          description: Steps to follow, in order.
          items:
            $ref: '#/components/schemas/GuidedAction'
        description:
          type: string
          description: Description of the sequence.
    EvidenceSourceKind:
      type: string
      enum:
        - EVIDENCE_SOURCE_KIND_UNSPECIFIED
        - FEATURE_QUALIFIER
        - FEATURE_FIT
        - OFFLINE_EVALUATION
    GuidedAction:
      type: object
      additionalProperties: false
      properties:
        description:
          type: string
          description: Description of the step.
        openDashboardPage:
          $ref: '#/components/schemas/OpenDashboardPageAction'
    OpenDashboardPageAction:
      type: object
      additionalProperties: false
      description: Opens a page of the Algolia dashboard.
      properties:
        url:
          type: string
          description: URL of the dashboard page.
  responses:
    BadRequest-2:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 400
            message: Bad request.
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 401
            message: Unauthorized.
    Forbidden:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 403
            message: Forbidden.
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-algolia-application-id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: x-algolia-api-key
      description: >
        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.

````