Perplexity API SDK for PHP

A lightweight PSR-17/PSR-18 client for the current Perplexity API, with examples for every exposed SDK method, SSE streaming, structured errors, compatible endpoint overrides, and separate organization analytics authentication.

Requirements

• PHP 8.1 or newer. CI tests PHP 8.1, 8.2, 8.3, 8.4, and 8.5.
• A PSR-17 request, stream, and URI factory.
• A PSR-18 HTTP client.
• The JSON extension.

Guzzle is used below because it provides both the PSR-17 factories and PSR-18 client implementation. The SDK itself depends only on the PSR interfaces, so other compliant implementations remain supported.

Installation

composer require softcreatr/php-perplexity-ai-sdk guzzlehttp/guzzle

Client Setup

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use SoftCreatR\PerplexityAI\PerplexityAI;

$factory = new HttpFactory();
$perplexity = new PerplexityAI(
    requestFactory: $factory,
    streamFactory: $factory,
    uriFactory: $factory,
    httpClient: new Client(['stream' => true]),
    apiKey: (string) getenv('PERPLEXITY_API_KEY'),
);

Keep API keys on the server and out of source control.

Agent API

The Agent API provides model and tool orchestration through a unified response interface.

use const JSON_THROW_ON_ERROR;

$response = $perplexity->createAgentResponse([
    'model' => 'openai/gpt-5-mini',
    'input' => 'Give me a one-sentence summary of PSR-18.',
]);

$result = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);

Endpoint methods return a PSR-7 ResponseInterface, including calls that deliver SSE events to a callback.

Sonar API

Sonar provides Perplexity's search-grounded chat completions.

$response = $perplexity->createChatCompletion([
    'model' => 'sonar',
    'messages' => [
        ['role' => 'user', 'content' => 'When did Wolfgang Amadeus Mozart die?'],
    ],
]);

Arguments

Body-only endpoints use a single body array:

$perplexity->createEmbedding([
    'model' => 'pplx-embed-v1-0.6b',
    'input' => 'A sentence to embed.',
]);

For endpoints with path parameters, a single combined array is the preferred v3 form. Path fields are separated from query or body fields using the endpoint template:

$perplexity->retrieveAgentResponse([
    'id' => 'resp_abc123',
]);

The v2 two-array form remains supported for existing integrations:

$perplexity->createChatCompletion([], [
    'model' => 'sonar',
    'messages' => [['role' => 'user', 'content' => 'Summarize PSR-18.']],
]);

For GET and DELETE methods, non-path values become RFC 3986 query parameters. Path parameter values are URL encoded. The explicit form is available when method names are determined at runtime:

$response = $perplexity->request(
    'retrieveAgentResponse',
    ['id' => 'resp_abc123'],
    customHeaders: ['X-Trace-Id' => 'trace_abc123'],
);

Streaming

Set stream to true and pass a callback. The decoder supports arbitrarily split chunks, CRLF and LF delimiters, comments, multiline data fields, final unterminated frames, and [DONE].

$perplexity->createChatCompletion(
    [
        'model' => 'sonar',
        'messages' => [['role' => 'user', 'content' => 'Write a short haiku about PHP.']],
        'stream' => true,
    ],
    static function (array $event): void {
        echo $event['choices'][0]['delta']['content'] ?? '';
    },
);

An ordinary JSON response is still returned when a callback is supplied without requesting an SSE stream. For a transport that exposes a response before buffering its complete body, implement StreamingClientInterface. Other PSR-18 clients remain supported and use their normal sendRequest() behavior.

Errors

4xx and 5xx responses throw PerplexityAIException. The exception keeps the parsed API error, raw response body, response headers, status code, and x-request-id for diagnostics.

use SoftCreatR\PerplexityAI\Exception\PerplexityAIException;

try {
    $perplexity->listModels();
} catch (PerplexityAIException $exception) {
    error_log(sprintf(
        'Perplexity request %s failed (%d): %s',
        $exception->getRequestId() ?? 'unknown',
        $exception->getCode(),
        $exception->getMessage(),
    ));
}

PSR-18 transport failures are wrapped in PerplexityAIException and retain the original exception as getPrevious().

Examples

Examples load the ignored project-level .env through examples/PerplexityAIFactory.php:

cp .env.example .env
php examples/sonar/createChatCompletion.php

Set PERPLEXITY_ANALYTICS_API_KEY only when running examples under examples/analytics.

Supported Methods

The catalog follows the current Perplexity API reference.

Agent

SDK method	HTTP route	Request body	Example
createAgentResponse	POST /v1/agent	json	PHP
retrieveAgentResponse	GET /v1/agent/{id}	none	PHP
listAgentResponseFiles	GET /v1/agent/{id}/files	none	PHP
downloadAgentResponseFile	GET /v1/agent/{id}/files/{file_id}/content	none	PHP
cancelAgentResponse	POST /v1/agent/{id}/cancel	none	PHP

Sonar

SDK method	HTTP route	Request body	Example
createChatCompletion	POST /v1/sonar	json	PHP
createAsyncChatCompletion	POST /v1/async/sonar	json	PHP
listAsyncChatCompletions	GET /v1/async/sonar	none	PHP
retrieveAsyncChatCompletion	GET /v1/async/sonar/{api_request}	none	PHP

Search

SDK method	HTTP route	Request body	Example
search	POST /search	json	PHP

Embeddings

SDK method	HTTP route	Request body	Example
createEmbedding	POST /v1/embeddings	json	PHP
createContextualizedEmbedding	POST /v1/contextualizedembeddings	json	PHP

Models

SDK method	HTTP route	Request body	Example
listModels	GET /v1/models	none	PHP

Router

SDK method	HTTP route	Request body	Example
createRouterChatCompletion	POST /router/v1/chat/completions	json	PHP
createRouterMessage	POST /router/v1/messages	json	PHP
createRouterResponse	POST /router/v1/responses	json	PHP
listRouterModels	GET /router/v1/models	none	PHP
retrieveRouterModel	GET /router/v1/models/{model}	none	PHP

Authentication

SDK method	HTTP route	Request body	Example
generateAuthToken	POST /generate_auth_token	json	PHP
revokeAuthToken	POST /revoke_auth_token	json	PHP

These operations manage live credentials. Review the examples before running them.

Analytics

SDK method	HTTP route	Request body	Example
getComputerUsageAnalytics	GET /v1/analytics/computer/usage	none	PHP
getComputerUsageAnalyticsV2	GET /v2/analytics/computer/usage	none	PHP

Analytics endpoints require a separate organization analytics API key. The example factory reads it from PERPLEXITY_ANALYTICS_API_KEY.

Custom API Origin

Pass a hostname or absolute base URL through the constructor's origin argument. basePath overrides any path already present in an absolute origin. The examples read PERPLEXITY_API_ORIGIN and PERPLEXITY_API_BASE_PATH from .env.

Development

composer install
composer test
composer analyse
vendor/bin/php-cs-fixer fix --dry-run --diff

License

Licensed under the ISC License.