api.md

Models

import type { Model, ModelListResponse } from '@perplexity-ai/perplexity_ai/resources/models';

const models = await client.models.list();

client.models.list() sends GET /v1/models and returns a ModelListResponse containing the models available for the Agent API.

Decisions

import type {
  DecisionCreateParams,
  DecisionCreateResponse,
} from '@perplexity-ai/perplexity_ai/resources/decisions';

const response = await client.decisions.create({
  model: 'pplx-decider-v1.1-27b',
  state: 'The battery stopped charging.',
  questions: { defect: { type: 'noul', instructions: 'Does this report a defect?' } },
});

client.decisions.create(...) sends POST /v1/decisions and returns a DecisionCreateResponse with named noul, choice, or score answers.

Shared

Types:

• APIPublicSearchResult
• BrowserSessionResponse
• ChatMessageInput
• ChatMessageOutput
• Choice
• ContextualizedEmbeddingObject
• EmbeddingObject
• EmbeddingsUsage
• JsonSchemaFormat
• ResponseFormat
• SearchResult
• UsageInfo
• UserLocation
• WebSearchOptions

Chat

Types:

• StreamChunk

Completions

Methods:

• client.chat.completions.create({ ...params }) -> StreamChunk

Search

Types:

• SearchCreateResponse

Methods:

• client.search.create({ ...params }) -> SearchCreateResponse

Responses

Types:

• Annotation
• ContentPart
• ErrorInfo
• FunctionCallOutputItem
• FunctionTool
• InputItem
• OutputItem
• ResponseFile
• ResponseFileList
• ResponseStreamChunk
• ResponsesCreateParams
• ResponsesUsage
• ResponseCreateResponse
• ResponseRetrieveResponse
• ResponseCancelResponse

Methods:

• client.responses.create({ ...params }) -> ResponseCreateResponse
• client.responses.retrieve(responseID) -> ResponseRetrieveResponse
• client.responses.cancel(responseID) -> ResponseCancelResponse

To reconnect to a background response's event stream, supply the last event sequence number received:

const stream = await client.responses.retrieve(responseID, {
  stream: true,
  starting_after: lastSequenceNumber,
});

Streaming retrieval requires starting_after. If the API returns HTTP 400 because the cursor has expired, call client.responses.retrieve(responseID) without streaming parameters to obtain the current JSON snapshot.

Files

Methods:

• client.responses.files.list(responseID) -> ResponseFileList
• client.responses.files.content(fileID, { ...params }) -> Response

Embeddings

Types:

• EmbeddingCreateResponse

Methods:

• client.embeddings.create({ ...params }) -> EmbeddingCreateResponse

ContextualizedEmbeddings

Types:

• ContextualizedEmbeddingCreateResponse

Methods:

• client.contextualizedEmbeddings.create({ ...params }) -> ContextualizedEmbeddingCreateResponse

Skills

Upload custom Skill ZIP bundles with a File or Blob; toFile normalizes byte buffers and other supported upload sources. Updates and deletion require expected_revision set to the Skill's current latest_revision. Pass next_page_token as page_token to fetch another page.

import Perplexity, { toFile } from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();
const file = await toFile(zipBytes, 'bundle.zip', { type: 'application/zip' });
let skill = await client.skills.create({ file });
const page = await client.skills.list({ limit: 20 });
skill = await client.skills.retrieve(skill.skill_id);
if (skill.latest_revision == null) throw new Error('A current revision is required to update');
skill = await client.skills.update(skill.skill_id, { file }, { expected_revision: skill.latest_revision });
if (skill.latest_revision == null) throw new Error('A current revision is required to delete');
const revisions = await client.skills.revisions.list(skill.skill_id);
const download = await client.skills.download(skill.skill_id, { revision: skill.latest_revision });
await client.skills.delete(skill.skill_id, { expected_revision: skill.latest_revision });

download returns a signed URL and revision; it does not fetch the ZIP.

Browser

Sessions

Methods:

• client.browser.sessions.create() -> BrowserSessionResponse
• client.browser.sessions.delete(sessionID) -> void

Async

Chat

Completions

Types:

• CompletionCreateResponse
• CompletionListResponse
• CompletionGetResponse

Methods:

• client.async.chat.completions.create({ ...params }) -> CompletionCreateResponse
• client.async.chat.completions.list() -> CompletionListResponse
• client.async.chat.completions.get(apiRequest, { ...params }) -> CompletionGetResponse