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 (active_profile_id on create-thread,
set_active_profile_id 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.
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 |