Agents
17 operations. {prefix} is the route prefix passed to
MapAgentPrism; the template uses /agentprism.
GET {prefix}/api/agents
Section titled “GET {prefix}/api/agents”Operation ID: AgentPrismListAgents
Lists all agents defined in code and in the database.
The list merges every registered agent source into a single view, ordered by name. When two sources hold the same name, the source with the higher priority wins and the other one is dropped from the list — code definitions win over database definitions. The response is not paged; the number of agents is bounded by the control plane, not by traffic. Each entry carries the origin, so a client can tell an editable definition from a code-defined one.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of AgentDescriptor |
— |
POST {prefix}/api/agents
Section titled “POST {prefix}/api/agents”Operation ID: AgentPrismCreateAgent
Creates a new agent definition.
The definition is fully validated before it is stored: the model binding, every tool, skill, and callable agent must already exist, and the call graph must be free of cycles. A failed check returns 400 and nothing is written. A name that another definition already uses returns 409; a name that a code-defined agent already uses also returns 409, because code wins name conflicts and the stored definition would never resolve. On success the response is 201 with the saved definition at version 1 and a Location header pointing at it.
Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.
Request body (required):
application/json→AgentDefinitionRequest
| Response | Body | Headers |
|---|---|---|
| 201 Created | application/json → AgentDefinition |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/agents/{name}
Section titled “GET {prefix}/api/agents/{name}”Operation ID: AgentPrismGetAgent
Returns an agent’s catalog summary and its persisted definition, if any.
A code-defined agent resolves through the catalog but has no stored definition; for it ‘definition’ is null and ‘isEditable’ is false. ‘isEditable’ is the single field a client checks before offering an edit form — it is true only when the agent’s origin is the database.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → AgentDetailResponse |
— |
PUT {prefix}/api/agents/{name}
Section titled “PUT {prefix}/api/agents/{name}”Operation ID: AgentPrismUpdateAgent
Updates an agent definition and produces a new version.
An agent’s name is immutable: when the path name and the body name differ the response is 400. A code-defined name returns 409 — code definitions are validated at compile time and are changed by changing the application. The same existence and call-graph checks as create apply, and a failed check writes nothing. Every successful save appends a version rather than overwriting; the previous content stays readable through the version history.
Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (required):
application/json→AgentDefinitionRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → AgentDefinition |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
DELETE {prefix}/api/agents/{name}
Section titled “DELETE {prefix}/api/agents/{name}”Operation ID: AgentPrismDeleteAgent
Deletes an agent definition and its version history.
The delete removes the current definition together with every stored version; it is not a soft delete and there is no rollback afterwards. A code-defined name returns 409. A name with no stored definition returns 404, so the call is not idempotent across repeats. Runs already recorded for the agent are kept — the run history does not depend on the definition still existing.
Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 204 No Content | — | — |
POST {prefix}/api/agents/{name}/estimate
Section titled “POST {prefix}/api/agents/{name}/estimate”Operation ID: AgentPrismEstimateContextWindow
Estimates a prompt’s token count against the agent’s model, without calling the provider.
The diagnostic surface of the pre-flight context-window check: it returns the same numbers the check on ‘POST /api/agents/{name}/run’ would use, regardless of whether that check is enabled. No model provider is ever contacted. The estimate is approximate — it uses a fixed reference tokenizer, not the bound provider’s own count. ‘contextWindowTokens’ and ‘allowedPromptTokens’ are null when the agent’s model is not found in the catalog; in that case ‘wouldBeRejected’ is always false, since an unknown window can never be exceeded.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (required):
application/json→AgentRunRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → ContextWindowEstimate |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
POST {prefix}/api/agents/{name}/rollback
Section titled “POST {prefix}/api/agents/{name}/rollback”Operation ID: AgentPrismRollbackAgent
Writes a definition as a new version with the content of a previous version.
A rollback moves forward, not backward: the old content is appended as a NEW version and the history is never rewritten, so the rollback itself stays auditable and can be rolled back in turn. An unknown version number returns 404; a code-defined name returns 409.
Authorization: bearer authentication; Admin role policy when that policy is registered; AgentsAdmin API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (required):
application/json→AgentRollbackRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → AgentDefinition |
— |
POST {prefix}/api/agents/{name}/run
Section titled “POST {prefix}/api/agents/{name}/run”Operation ID: AgentPrismRunAgent
Runs an agent for trial purposes and streams the response via SSE.
If the quota is exceeded, the run does not start and a 429 is returned; the ProblemDetails carries which quota was exceeded and when the counter resets. When the pre-flight context-window check is enabled (disabled by default) and the prompt is estimated to exceed the model’s window, the run does not start and a 400 is returned with the estimated and allowed token counts; no call reaches the provider. A request carrying the ‘Idempotency-Key’ header runs with a single JSON response (non-streaming) instead of SSE, because a replayed response cannot be reconstructed from a stream. A request carrying the ‘Prefer: respond-async’ header queues the run and returns ‘202 Accepted’ with a ‘Location’ header. If a registered IContentGuard blocks the content, the non-streaming response returns ‘422’ and the run’s error type becomes ‘content_blocked’; in the STREAMING response the status code has already been sent, so the block arrives as an SSE ‘error’ event instead.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (required):
application/json→AgentRunRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | text/event-stream → string |
— |
| 202 Accepted | application/json → AcceptedRunResponse |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
| 422 Unprocessable Entity | application/problem+json → ProblemDetails |
— |
| 429 Too Many Requests | application/problem+json → ProblemDetails |
— |
| 501 Not Implemented | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/agents/{name}/versions
Section titled “GET {prefix}/api/agents/{name}/versions”Operation ID: AgentPrismListAgentVersions
Lists a definition’s version history, newest first.
Every entry is a full definition snapshot, not a delta, so a single entry is enough to inspect or restore a past state. The agent must have a current stored definition; a code-defined or deleted name returns 404. Code agents have no version history at all — their history is the application’s source history.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of AgentDefinition |
— |
GET {prefix}/api/agents/{name}/versions/{a}/diff/{b}
Section titled “GET {prefix}/api/agents/{name}/versions/{a}/diff/{b}”Operation ID: AgentPrismGetAgentVersionDiff
Returns two definition versions as raw JSON; the diff is computed in the UI.
The server does no diffing and takes no position on how a change should be displayed; it returns both snapshots verbatim as ‘left’ and ‘right’ so the client chooses the presentation. The two version numbers may be given in any order. When either version is missing the response is 404 and names the one that was not found.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
a |
path | yes | integer (int32) |
pattern `^-?(?:0\ |
b |
path | yes | integer (int32) |
pattern `^-?(?:0\ |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → AgentVersionDiffResponse |
— |
POST {prefix}/api/agents/validate
Section titled “POST {prefix}/api/agents/validate”Operation ID: AgentPrismValidateAgent
Compiles a definition without saving it and without calling any model.
A validation failure is NOT an HTTP error. When the body is well-formed the response is always 200 and the outcome is carried in the report’s ‘valid’ field, with one message per finding. 400 is returned only when the body itself cannot be read or the required name/model fields are missing — that is the single case a pipeline needs in order to tell a transport error from a rejected definition. No model provider is contacted and nothing is written.
Authorization: bearer authentication; Operator role policy when that policy is registered; AgentsAdmin API-key scope.
Request body (required):
application/json→AgentDefinitionRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → AgentValidationReport |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/models
Section titled “GET {prefix}/api/models”Operation ID: AgentPrismListModels
Lists registered model providers and their models.
The model catalog comes from configuration; AgentPrism does not ship a built-in model list. An empty list is not an error. The catalog is also not a validation list: a model name that is not listed here can still be used. The status field comes FROM THE CACHE, and this endpoint makes no network call to the provider; use /api/models/health for an up-to-date check.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of ModelProviderDescriptor |
— |
GET {prefix}/api/stats
Section titled “GET {prefix}/api/stats”Operation ID: AgentPrismStats
Returns run counts, token totals, and the error rate.
The summary is computed in the store itself. Cost is populated only when pricing is configured (model catalog or AgentPrism:Pricing); the count of models with undefined pricing is counted separately in the RunsWithUnknownPricing field — it is not written as zero. Every breakdown (byAgent, byModel, byVersion, byUser, byLabel) is ALWAYS returned; there is no groupBy switch. ‘userId’ and ‘label’ (‘key:value’) narrow the whole summary rather than choosing a breakdown. 🚨 byLabel rows do NOT sum to totalRuns: a run carrying three labels appears in three of them. cachedInputTokens and reasoningTokens are counted INSIDE inputTokens/outputTokens, so adding them double counts.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
agentName |
query | no | string |
— |
userId |
query | no | string |
— |
label |
query | no | string |
— |
startedAfter |
query | no | string (date-time) |
— |
maxAgents |
query | no | integer (int32) |
pattern `^-?(?:0\ |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → RunStatistics |
— |
GET {prefix}/api/stats/errors
Section titled “GET {prefix}/api/stats/errors”Operation ID: AgentPrismStatsErrors
Returns the breakdown by error class and each class’s top three clusters.
This is a narrow slice of /api/stats: it returns only the ByErrorClass field (that field is also present in the /api/stats response). The default range is the last 24 hours, changed with ?hours=. Rows written before error classification existed appear in the Unknown bucket; a high Unknown share means the taxonomy is incomplete.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
agentName |
query | no | string |
— |
hours |
query | no | number (double) |
pattern `^-?(?:0\ |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of RunErrorStatistics |
— |
POST {prefix}/api/stats/recalculate-costs
Section titled “POST {prefix}/api/stats/recalculate-costs”Operation ID: AgentPrismRecalculateCosts
Recalculates the cost of all runs based on the current pricing source.
This is a maintenance endpoint. It is used to refresh past runs when pricing is defined later. The provider is not kept on historical rows; if the same model name is defined for more than one provider, the first alphabetical match wins. Requires Admin; the call is written to the audit trail.
Authorization: bearer authentication; Admin role policy when that policy is registered; RunsWrite API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → RunCostRecalculationResult |
— |
GET {prefix}/api/stats/timeseries
Section titled “GET {prefix}/api/stats/timeseries”Operation ID: AgentPrismStatsTimeSeries
Per-bucket time series of runs, errors, tokens, and cost.
Empty buckets are returned too. The default range is the last 24 hours, the default bucket is an hour. At most 500 buckets; exceeding that returns 400. Unlike /api/stats, this endpoint does NOT exclude Eval/Workflow runs by default; it can be filtered with ?kind=.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
from |
query | no | string (date-time) |
— |
to |
query | no | string (date-time) |
— |
bucket |
query | no | TimeSeriesBucket |
— |
agentName |
query | no | string |
— |
modelId |
query | no | string |
— |
kind |
query | no | RunKind |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of TimeSeriesPoint |
— |
GET {prefix}/api/tools
Section titled “GET {prefix}/api/tools”Operation ID: AgentPrismListTools
Lists registered tools and their JSON schemas.
Tools are defined only in code. This endpoint does not offer a write path; the UI lets users pick from this list when defining an agent.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of ToolDescriptor |
— |