Version: Dev

Perplexity

Perplexity's Agent API combines third-party language models with Perplexity-hosted search and agent tools. Applications call the provider-native API through AISIX while the gateway holds the Perplexity credential and controls which callers can use the route.

Perplexity ended Sonar Chat Completions support on September 27, 2026. Its migration guide documents transitional reformulation for some synchronous and streaming Sonar requests, while Perplexity does not reformulate asynchronous requests. Do not rely on this compatibility behavior. New integrations should use the Agent API, and existing Sonar integrations should follow Perplexity's migration guide.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
A Perplexity API key. See API Key Management.
curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details and the Perplexity credential:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export PERPLEXITY_API_KEY="YOUR_PERPLEXITY_API_KEY"

Create a provider key that stores the Perplexity credential:

if ! PROVIDER_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Perplexity Agent API",
    "provider": "perplexity",
    "api_key": "'"${PERPLEXITY_API_KEY}"'",
    "api_base": "https://api.perplexity.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'); then
  printf '%s\n' "$PROVIDER_RESPONSE" >&2
  false
elif ! PROVIDER_KEY_ID=$(printf '%s' "$PROVIDER_RESPONSE" | jq -er '.provider_key.id'); then
  printf '%s\n' "$PROVIDER_RESPONSE" >&2
  false
fi

Create a passthrough route that mounts Perplexity's /v1 API at /passthrough/perplexity:

if ! ROUTE_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/passthrough_routes" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "perplexity-agent",
    "path_prefix": "/passthrough/perplexity",
    "target_url": "https://api.perplexity.ai/v1",
    "credential_mode": "inject",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'); then
  printf '%s\n' "$ROUTE_RESPONSE" >&2
  false
else
  printf '%s' "$ROUTE_RESPONSE" | jq '.warnings // []'
fi

The route removes /passthrough/perplexity before joining the remaining path to target_url. A request to /passthrough/perplexity/agent therefore reaches Perplexity's canonical POST /v1/agent endpoint.

Create a caller key that grants access to this route. The plaintext is returned once:

if ! CALLER_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Perplexity Agent caller",
    "allowed_models": [],
    "allowed_routes": ["perplexity-agent"]
  }'); then
  printf '%s\n' "$CALLER_RESPONSE" >&2
  false
elif ! AISIX_API_KEY=$(printf '%s' "$CALLER_RESPONSE" | jq -er '.plaintext'); then
  printf '%s\n' "$CALLER_RESPONSE" >&2
  false
else
  export AISIX_API_KEY
  printf '%s' "$CALLER_RESPONSE" | jq '.warnings // []'
fi

The control plane projects the provider key, route, and caller grant to attached gateways. Review any compatibility warnings before rollout, then verify traffic through each gateway.

Configure with the Open-Source AISIX Gateway

Export the upstream and caller credentials:

export PERPLEXITY_API_KEY="YOUR_PERPLEXITY_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "perplexity-agent"
    provider: "perplexity"
    adapter: "openai"
    api_key: ${PERPLEXITY_API_KEY}
    api_base: "https://api.perplexity.ai/v1"

passthrough_routes:
  - name: "perplexity-agent"
    path_prefix: "/passthrough/perplexity"
    target_url: "https://api.perplexity.ai/v1"
    provider_key: "perplexity-agent"

api_keys:
  - display_name: "perplexity-agent-caller"
    key_env: CALLER_API_KEY
    allowed_models: []
    allowed_routes:
      - "perplexity-agent"

Validate the complete file before loading it:

aisix validate --resources resources.yaml

Start the gateway with both environment variables available to its process. If you use Docker, pass them with -e during validation and startup, as shown in the Open-Source AISIX Gateway Quickstart.

After the resources load, prepare the caller credential for the shared verification request:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Agent API Route

Export the AISIX gateway origin:

# AISIX_PROXY has no trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

Send a request with Perplexity's fast preset, which is suited to quick web-grounded answers:

curl --fail-with-body -sS -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "fast",
    "input": "Summarize the latest news about AI gateways in two sentences."
  }'

AISIX authenticates the caller, checks the perplexity-agent route grant, injects the provider credential, and relays Perplexity's native response. The gateway does not rewrite presets, model identifiers, request fields, or response fields on a passthrough route.

Perplexity manages the model, tools, and search configuration behind a dynamic preset and can update that configuration. Use an explicit model from Perplexity's current Agent API model list when the application must select a model directly. See Presets for the tradeoffs between fast, low, medium, high, and xhigh.

Stream a Response

Set stream to true to relay the Agent API's typed server-sent events:

curl --fail-with-body -sS -N -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "fast",
    "input": "What changed in AI gateway technology this week?",
    "stream": true
  }'

The stream contains typed events such as output-text deltas and tool activity. Applications migrating from Sonar must update consumers that expect Chat Completions chunks under choices[].delta.content.

Run a Request in the Background

For a long-running task, set background to true and capture the response ID:

if ! RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "high",
    "input": "Compare the latest approaches to AI gateway reliability.",
    "background": true
  }'); then
  printf '%s\n' "$RESPONSE" >&2
  false
elif ! RESPONSE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id'); then
  printf '%s\n' "$RESPONSE" >&2
  false
else
  echo "$RESPONSE_ID"
fi

Retrieve the response by ID through the same route:

curl --fail-with-body -sS \
  "$AISIX_PROXY/passthrough/perplexity/agent/$RESPONSE_ID" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

Poll until the response reaches a terminal status. Perplexity's Background Mode also documents reconnection, event streaming, and cancellation. This is the replacement for Sonar's retired asynchronous API; AISIX does not convert an old asynchronous Sonar request into a background Agent API run.

Troubleshoot the Connection

Error or symptom	What to check
AISIX returns `403` before contacting Perplexity	Confirm the caller key's `allowed_routes` list includes `perplexity-agent`. Model grants do not grant access to passthrough routes.
Perplexity returns `401` or `403`	Confirm the provider key contains an active Perplexity credential. For `403`, also confirm the Perplexity account can use the requested preset, model, or tool.
Perplexity returns `404`	Confirm the route target is `https://api.perplexity.ai/v1` and the gateway request uses `/passthrough/perplexity/agent`. The Search API uses a separate root and cannot use this route.
Perplexity rejects a preset or model	Use a preset from the current preset list or an exact model ID from the Agent API model list. Do not send a retired Sonar model name to the Agent API.
Retrieving a background response returns `404`	Use the response ID returned by the background submission and the same Perplexity credential. An unknown ID or a response owned by another account returns `404`.

Use an AISIX Model Alias

The passthrough setup is the preferred path for presets and the complete provider-native contract. If an application needs an AISIX model alias for model-level routing, limits, or cost metadata, configure a separate model-backed path:

Set the provider key's api_base to https://api.perplexity.ai/v1.
Add apis.responses: {} to declare Perplexity's native Responses-compatible endpoint.
Create a model alias whose model_name is an exact model ID from Perplexity's current Agent API model list.
Create or update a caller key so its allowed_models list grants the alias. In AISIX Cloud, use the model resource ID; in a resources file, use the alias's display_name.
Call AISIX at /v1/responses with the alias in model.

The passthrough-only caller created earlier has an empty allowed_models list. It cannot call the model alias until you grant the alias or use a separate model-enabled caller.

AISIX then sends the request to Perplexity's /v1/responses alias for the Agent API, rewrites the AISIX alias to the upstream model ID, and restores the alias in the response. The caller request must contain model, so this normalized path cannot use a preset as the sole configuration. It also cannot call Perplexity's background retrieval path by response ID. Use the passthrough route for those workflows.

Without apis.responses, AISIX treats /v1/responses as a cross-provider bridge and translates the request to the provider key's Chat Completions route. That path does not call the native Agent API and cannot preserve Agent API-only fields or output items.

API Boundaries

Perplexity publishes the Agent and Embeddings APIs under the /v1 root. The configured passthrough route can reach both native endpoints, but it does not give them one shared request or response schema. Perplexity serves the Search API at /search without the /v1 prefix, so it requires a separate passthrough route whose target is https://api.perplexity.ai.

The passthrough rows below use the primary setup on this page. The normalized routes require the optional model alias and a caller key that grants it, as described in Use an AISIX Model Alias.

AISIX route	Behavior
`/passthrough/perplexity/agent`	Calls the canonical Agent API. Supports synchronous, streaming, and background requests.
`/passthrough/perplexity/responses`	Calls the OpenAI-compatible alias for the Agent API. Perplexity recommends its own SDK for the complete native contract.
`/passthrough/perplexity/models`	Lists the currently available Agent API models in OpenAI-compatible format.
`/passthrough/perplexity/embeddings`	Calls Perplexity's standard Embeddings API.
`/passthrough/perplexity/contextualizedembeddings`	Calls Perplexity's Contextualized Embeddings API for document chunks that share context.
`/v1/chat/completions`	Requires the optional model alias and model-enabled caller. Do not use this route with the provider key on this page: AISIX appends `/chat/completions` to `api_base` and targets the undocumented `https://api.perplexity.ai/v1/chat/completions` path. Use the passthrough Agent API route or configure native `/v1/responses` instead.
`/v1/responses`	Requires the optional model alias and model-enabled caller. It calls the native Agent API only when the provider key declares `apis.responses` and the request names the AISIX alias. Otherwise, AISIX bridges the request through Chat Completions.
`/v1/messages`	Not supported with the configuration on this page. AISIX would translate the Anthropic-shaped request through Chat Completions and target the undocumented `/v1/chat/completions` path. Use the passthrough Agent API route or the native `/v1/responses` path instead.

Passthrough token counts are telemetry only. When a top-level model value matches a same-provider AISIX alias, that alias's request-count limit can apply. Passthrough token usage does not advance tpm or tpd counters, resolve AISIX model cost metadata, or add budget spend. See Passthrough Routes.

Perplexity's standard embedding models return quantized base64 strings rather than float arrays. Decode base64_int8 values and compare them with cosine similarity, or compare base64_binary values with Hamming distance, as described in Perplexity's embedding best practices.

Next Steps

Passthrough Routes: review authentication, route matching, headers, guardrails, and telemetry.
Provider Keys: configure credential handling and native API declarations.
Model Aliases: configure a model-backed Agent API path when callers need AISIX model controls.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Configure with the Open-Source AISIX Gateway​

Verify the Agent API Route​

Stream a Response​

Run a Request in the Background​

Troubleshoot the Connection​

Use an AISIX Model Alias​

API Boundaries​

Next Steps​