Agent Profile APIs
Programmatic management of agent profiles — saved, versioned bundles of agent configuration (system prompt, model, tools, prompt variables) that a conversation points at instead of assembling the same generation config on every call — and the shared prompt fragments those profiles compose.
This is the write side. Selecting a profile for a conversation lives on the
LLM APIs (activeProfileId on create-thread,
setActiveProfileId on send-message).
Authentication
Agent profiles are tenant-scoped configuration, not per-user data, so these
endpoints authenticate with a secret key alone — no X-On-Behalf-Of, no end-user
JWT. A profile belongs to your tenant, not to one of your users.
Same model as the Webhook APIs. It differs
from the LLM, storage and end-user APIs, where a secret key without X-On-Behalf-Of
returns 401 authenticated user_id is required.
Scoping
Tenant is derived server-side from the verified key — there is no tenant field in any
request body, and a ctx object sent in a body is overwritten and ignored.
Every profile and fragment also lives in a project, addressed with the optional
X-Project-Id header. Until the Projects feature ships, default is the only valid
project and is what you get when the header is omitted.
Field naming
Request bodies accept either snake_case or camelCase — both parse. Response
bodies are always camelCase (profileId, whenToUse, generationConfig),
because responses are encoded with protojson. Fields that are unset, empty, zero, or
false are omitted from the response entirely rather than sent as null — read
them with a default, not a presence check.
All endpoints use POST with a JSON request body.
Authentication
- API Key: apiKeyAuth
Your secret key, sk_…. Sufficient on its own for this API — agent profiles are
tenant-scoped configuration, so no acting user is required.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |