Skip to main content
POST
/
1
/
agents
/
{agentId}
/
completions
curl
curl --request POST \
  --url 'https://example.algolia.net/agent-studio/1/agents/lorem/completions?compatibilityMode=ai-sdk-4&stream=true&cache=true&memory=false&analytics=true' \
  --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' \
  --header 'x-algolia-secure-user-token: lorem' \
  --data '
{
  "configuration": {
    "id": "lorem",
    "providerId": "lorem",
    "model": "lorem",
    "instructions": "lorem",
    "systemPrompt": "lorem",
    "config": {},
    "tools": [
      {
        "name": "lorem",
        "type": "client_side",
        "description": "lorem",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": [
            "lorem"
          ]
        }
      }
    ]
  },
  "messages": [
    {
      "id": "lorem",
      "role": "user",
      "content": "lorem",
      "parts": [
        {
          "type": "text",
          "text": "lorem"
        }
      ],
      "annotations": [
        {}
      ]
    }
  ],
  "id": "lorem",
  "algolia": {
    "mcpServers": {
      "property1": {
        "property1": {
          "property1": "lorem",
          "property2": "lorem"
        },
        "property2": {
          "property1": "lorem",
          "property2": "lorem"
        }
      },
      "property2": {
        "property1": {
          "property1": "lorem",
          "property2": "lorem"
        },
        "property2": {
          "property1": "lorem",
          "property2": "lorem"
        }
      }
    },
    "searchParameters": {
      "property1": {
        "filters": "lorem",
        "attributesToRetrieve": [
          "lorem"
        ],
        "restrictSearchableAttributes": [
          "lorem"
        ],
        "distinct": true,
        "userToken": "lorem",
        "enablePersonalization": true,
        "personalizationImpact": 42,
        "optionalFilters": "lorem"
      },
      "property2": {
        "filters": "lorem",
        "attributesToRetrieve": [
          "lorem"
        ],
        "restrictSearchableAttributes": [
          "lorem"
        ],
        "distinct": true,
        "userToken": "lorem",
        "enablePersonalization": true,
        "personalizationImpact": 42,
        "optionalFilters": "lorem"
      }
    }
  },
  "toolApprovals": {}
}
'
{}
This endpoint handles two types of requests:
  1. Normal completion request: User message -> Agent response
  2. Tool approval response: User approval -> Execute tool -> Agent response
Tool Approval Flow (for MCP tools with requiresApproval: true):
  • Request 1: User sends message -> Agent requests tool call -> Return approval request
  • Request 2: User approves -> Execute tool -> Agent continues with result.
Required ACL: search

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.

Headers

​
X-Algolia-Secure-User-Token
string | null

The X-Algolia-Secure-User-Token.

Path Parameters

​
agentId
required

The agentId.

Query Parameters

​
compatibilityMode
enum<string>
required

Compatibility mode for the completion API. Support Compatibility modes for the completion API.

Available options:
ai-sdk-4,
ai-sdk-5
​
analytics
boolean
default:true

Set to false to skip analytics for this completion (default: true). Disables Agent Studio BigQuery analytics, Algolia search analytics, click analytics, and query-suggestions training. Useful for offline-eval workflows.

​
cache
boolean
default:true

Use cached responses if available.

​
memory
boolean | null

Set to false to disable memory (enabled by default).

​
stream
boolean
default:true

Whether to stream the response or not.

Body

application/json

Request model for creating a completion for an assistant.

​
algolia
agentCompletionAlgoliaParams · object
​
configuration
agentTestConfiguration · object

Dynamic configuration for testing agents.

​
id
string

Optional conversation id.

Maximum string length: 128
​
messages
​
toolApprovals
toolApprovals · object

Approval decisions for pending tool calls keyed by toolCallId.

Response

Successful Response.

The response is of type object.

Last modified on June 11, 2026