api.md

Models

from perplexity.types import Model, ModelListResponse

models = client.models.list()

client.models.list() sends GET /v1/models and returns a ModelListResponse containing the models available for the Agent API. AsyncPerplexity exposes the same method with await.

Decisions

from perplexity.types import (
    DecisionAnswer,
    DecisionCreateParams,
    DecisionCreateResponse,
    DecisionQuestion,
)

response = 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. AsyncPerplexity exposes the same method with await.

Shared Types

from perplexity.types import (
    APIPublicSearchResult,
    BrowserSessionResponse,
    ChatMessageInput,
    ChatMessageOutput,
    Choice,
    ContextualizedEmbeddingObject,
    EmbeddingObject,
    EmbeddingsUsage,
    JsonSchemaFormat,
    ResponseFormat,
    SearchResult,
    UsageInfo,
    UserLocation,
    WebSearchOptions,
)

Chat

Types:

from perplexity.types import StreamChunk

Completions

Methods:

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

Search

Types:

from perplexity.types import SearchCreateResponse

Methods:

• client.search.create(**params) -> SearchCreateResponse

Responses

Types:

from perplexity.types import (
    Annotation,
    ContentPart,
    ErrorInfo,
    FunctionCallOutputItem,
    FunctionToolParam,
    InputItemParam,
    OutputItem,
    ResponseFile,
    ResponseFileList,
    ResponseStreamChunk,
    ResponseCreateParams,
    ResponsesUsage,
    ResponseCreateResponse,
    ResponseRetrieveResponse,
    ResponseCancelResponse,
)

Methods:

• client.responses.create(**params) -> ResponseCreateResponse
• client.responses.retrieve(response_id) -> ResponseRetrieveResponse
• client.responses.cancel(response_id) -> ResponseCancelResponse

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

stream = client.responses.retrieve(response_id, stream=True, starting_after=last_sequence_number)

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

Files

Methods:

• client.responses.files.list(response_id) -> ResponseFileList
• client.responses.files.content(file_id, *, response_id) -> BinaryAPIResponse

Embeddings

Types:

from perplexity.types import EmbeddingCreateResponse

Methods:

• client.embeddings.create(**params) -> EmbeddingCreateResponse

ContextualizedEmbeddings

Types:

from perplexity.types import ContextualizedEmbeddingCreateResponse

Methods:

• client.contextualized_embeddings.create(**params) -> ContextualizedEmbeddingCreateResponse

Skills

Upload custom Skill ZIP bundles using bytes or (filename, bytes, content_type). Updates and deletion require expected_revision set to the Skill's current latest_revision. List responses expose next_page_token; pass it as page_token to request another page.

skill = client.skills.create(file=("bundle.zip", zip_bytes, "application/zip"))
page = client.skills.list(limit=20)
skill = client.skills.retrieve(skill.skill_id)
if skill.latest_revision is None:
    raise ValueError("A current revision is required to update")
skill = client.skills.update(
    skill.skill_id,
    expected_revision=skill.latest_revision,
    file=("bundle.zip", zip_bytes, "application/zip"),
)
if skill.latest_revision is None:
    raise ValueError("A current revision is required to delete")
revisions = client.skills.revisions.list(skill.skill_id)
download = client.skills.download(skill.skill_id, revision=skill.latest_revision)
client.skills.delete(skill.skill_id, expected_revision=skill.latest_revision)

download returns a signed URL and revision; it does not fetch the ZIP. The same methods are available on AsyncPerplexity.

Browser

Sessions

Methods:

• client.browser.sessions.create() -> BrowserSessionResponse
• client.browser.sessions.delete(session_id) -> None

Async

Chat

Completions

Types:

from perplexity.types.async_.chat import (
    CompletionCreateResponse,
    CompletionListResponse,
    CompletionGetResponse,
)

Methods:

• client.async*.chat.completions.create(**params) -> CompletionCreateResponse
• client.async*.chat.completions.list() -> CompletionListResponse
• client.async*.chat.completions.get(api*request, **params) -> CompletionGetResponse