Perplexity Documents Versioned Agent API Profiles for Pinning Stable Configurations

Perplexity has documented Profiles, a reusable and versioned configuration layer for its Agent API. A profile stores the settings that shape an agent run under one ID, rather than requiring developers to repeat the full setup in each request. The key operational choice is whether to pin an exact version or let a request follow later changes through latest.

Profiles can bundle a model or model fallback chain, system instructions, reasoning effort, tools and an agent-loop step budget. They extend an Agent API introduced in March as a managed runtime for workflows with integrated search, tool execution and multi-model orchestration. The new layer is aimed at saving a configuration developers control, not merely saving a prompt.

Two paths for configuration control

A request must use either a preset or a profile, not both. Presets are maintained by Perplexity and resolve to its current recommended configuration. Profiles are defined and versioned by the developer, offering teams a way to take control of a setup rather than continually inherit a managed default.

One profile, with controlled exceptions

A profile supplies defaults rather than a sealed package. Request-level parameters override matching profile values, allowing a developer to change one setting for a run. Tools are the exception: their settings merge per tool, so changing one tool’s options leaves other profile tools enabled.

Updates become a release decision

Each profile version is immutable: editing a profile creates another version. A pinned request runs its selected configuration, while latest picks up newly uploaded versions. Perplexity resolves the version when a request is admitted, so an edit made during a run does not change that in-flight job.

Profile errors are request errors

• An unsupported model named in a profile fails before the run begins.
• An incorrect or inaccessible profile ID fails before the run begins.
• An invalid profile version fails before the run begins.

These problems return a 4xx status before agent execution starts. That makes version selection and profile access part of ordinary API error handling, while the pin-versus-latest choice determines whether later configuration edits reach a workload automatically.