Avatar API — Noolog Docs

Dashboard

GET / multi-agent dashboard HTML.

Returns Cache-Control: no-store so the browser always fetches the latest version after a rebuild (HTML is embedded at compile time via include_str!).

Responses

200Multi-agent dashboard HTML page

Agents

GET /api/agents list all agents with summary status.

Responses

200List of all agents with summary statusAgentSummary[]

GET /api/agents/errors fleet-wide API errors over the last 24h.

Reads each agent's NATS-persisted event log (24h retention) and aggregates the agent_error events into one operator view, so infra can be watched at a glance without pulling each agent's diagnostics individually.

Responses

200Fleet-wide API errors over the last 24hAgentErrorsReport

field	type		description
errors	AgentErrorEntry[]	required	Errors across all agents, newest first.
stream_cap	integer	required	Per-agent hard cap on retained events. The 24h window is bounded by this: an agent emitting more than this many events inside the window loses its oldest events to eviction.
total	integer	required	Number of errors in `errors`.
window_hours	integer	required	Rolling window, in hours.

GET /api/agents/{name}/diagnostics metrics + latest errors for one agent.

path parameters

name

string

required

Agent name

Responses

200Agent metrics + latest errorsAgentDiagnostics

field	type		description
error_rate	number	required
flag_reason	string \| null		Why it's flagged, if flagged.
is_flagged	boolean	required	Whether the agent is flagged for operator attention (e.g. score divergence from peers).
is_paused	boolean	required	Whether the agent is paused (e.g. auto-paused on a 402/billing error) — it pulls no new tasks while paused.
model_name	string	required
name	string	required
recent_errors	EventLogEntry[]	required	Most recent `agent_error` events (newest first), with their detail.
recent_failed_tasks	TaskLogEntry[]	required	Most recent tasks that ended in `"error"` (newest first).
tasks_completed	integer	required
tasks_failed	integer	required
uptime_secs	integer	required

404Unknown agent

GET /api/agents/{name}/tasks the agent's in-flight and finished tasks/queries over the last 24h, from its NATS event log.

path parameters

name

string

required

Agent name

Responses

200In-flight and finished tasksTasksView

field	type		description
finished	TaskView[]	required	Finished tasks, newest first.
in_flight	TaskView[]	required	Tasks started with no finish event yet, newest first.

404Unknown agent

GET /api/agents/{name}/tool-calls the agent's pending and finished tool invocations over the last 24h, from its NATS event log.

path parameters

name

string

required

Agent name

Responses

200Pending and finished tool callsToolCallsView

field	type		description
finished	ToolCallView[]	required	Finished tool calls, newest first.
pending	ToolCallView[]	required	Started tool calls with no finish event yet, newest first.

404Unknown agent

Status

GET /api/agents/{name}/config per-agent configuration.

Serializes the full AgentConfig directly. The orchestrators field is excluded automatically via #[serde(skip_serializing)] on the struct.

path parameters

name

string

required

Agent name

Responses

200Agent configurationAgentConfig

field	type		description
auto_stop	boolean		When true, buffer entries from this agent are created with `stopped = true`, preventing auto-release until an external system edits and explicitly releases them via `POST /buffer/{id}/release`. Used with stub providers for human-operated agents.
builtin_tools	BuiltinToolGrant[]		Per-agent grants for built-in sandboxed tools. Attached to an agent's tool list only for the native-LLM provider branch; `provider_type: claude` / `exec` / `mcp` route their tools through provider-native channels (claude sub-agents, the exec subprocess's own tool surface, MCP server) so grants configured on those agents are silently ignored at runtime (loaders are expected to warn). Use this to give native-LLM agents scoped runtime capabilities (e.g. read files confined to a specific filesystem root) without going through the user_tools NATS dispatcher pipeline. Each grant becomes a tool in the agent's tool list at startup. See `crate::tools::scoped_read` for the `read_file` implementation and its security model.
capability_tags	string[]		Free-form capability tags (e.g., `["legal", "audit", "quantitative"]`). Used for filtering in agent picker and directory.
chars_per_token	number \| null		Characters per token for heuristic estimation when the provider doesn't return usage stats. Deserialized as `Option<f64>` (None when absent in config). The runtime fallback of 4.0 (English approximation) is applied at the call site via `.unwrap_or(4.0)` in `nsed_agent.rs`; set lower (~1.5) for CJK/code.
claude	oneOf
compact_history_default_keep	integer		Default value of `compact_history(keep_last_n_calls)` when the model omits the argument. Two recent tool results give the model enough context to reason while older results fold into the scratchpad summary.
context_window	integer
description	string \| null		Short description of the agent's specialization. Shown in the agent directory and picker UI.
disable_native_tools	boolean
exec	oneOf
failure_dumps	string \| null		Controls failure dump output when parse or API errors occur. Values: `"on"` (default — dump error + raw response), `"full"` (include system prompt, request body, and messages), `"off"` (disable). Dumps are written to `failures/<session>_<agent>/`. Can also be set globally via the `NSED_FAILURE_DUMPS` env var (`1` = on, `full` = full). The config value takes precedence over the env var.
frequency_penalty	number \| null
input_price_per_mtok	number \| null		USD per million input tokens. Used for cost estimation in budget reporting.
json_mode	boolean
max_concurrent_jobs	integer \| null		Max jobs this agent runs concurrently. Enforced as the pull consumer's `max_ack_pending`, so the broker withholds the next task until an in-flight one finishes. Set to `1` for agents whose jobs mutate shared state (e.g. a git repo a middleware resets per job) to prevent races. `None` (default) leaves it unbounded.
max_react_iterations	integer \| null
max_retries	integer \| null
max_scratchpad_size	integer \| null
max_tokens	integer
mcp	oneOf
merge_system_prompt	boolean
model	string \| null		Dotpath model reference: `"provider_id.model_key"`. When set, resolves the provider and merges `ModelDef` fields into this agent at config load time (`load_agent_from_config`). Replaces the legacy `provider_id` + `model_name` + flat LLM field pattern.
model_name	string
name	string	required
openrouter	oneOf
output_price_per_mtok	number \| null		USD per million output tokens. Used for cost estimation in budget reporting.
persona	string \| null
presence_penalty	number \| null		Presence penalty for the model. Defaults to `Some(1.5)` to encourage diverse vocabulary in multi-agent deliberation (reduces repetitive phrasing across rounds). Set to `None` or `0.0` in config to disable.
prompt_exposure_guard	boolean		Enable the `prompt_exposure` safety guardrail on this agent's LLM responses. When `true`, the agent scans every terminal tool-call content (proposal / batch evaluation) for internal-prompt leakage (XML scaffolding tags, canonical tool names, meta-protocol phrases) and forces a retry with a block-reason feedback message when a leak is detected. Defaults to `false` so existing deployments do not change behavior until explicitly opted in. See [`docs/middleware.md#prompt_exposure-config`](../../docs/middleware.md) for the detection heuristics.
propagate_payment_error	boolean		Whether to propagate 402 Payment Required errors to the orchestrator. When `true` (default), an `agent_error` event is published immediately. When `false`, the agent silently pauses and lets the orchestrator timeout.
provider_config	object		Free-form provider config for third-party [`ProviderFactory`] implementations. Built-in providers (`exec` / `mcp` / `claude`) use their typed sections above; a custom `provider.type` reads its knobs from here, so registering a new provider needs no new field on this core struct. Deserialize the whole map into a typed struct with [`AgentConfig::provider_config_as`], or index the map directly. [`ProviderFactory`]: crate::providers::ProviderFactory
provider_id	string		Legacy provider reference. When `model` is set, this is overwritten during resolution. Kept for backward compatibility.
reasoning_effort	string \| null
repair_invalid_escapes	boolean
response_sla_secs	integer		Maximum seconds this agent needs to complete a single task (propose or evaluate). When > 0, this is a hard infrastructure constraint — the orchestrator will never give this agent less time than this value per phase. Set to `0` to opt out of SLA reporting (the field is omitted from heartbeats). Defaults to 3600s (1 hour).
scratchpad_limit	integer
scratchpad_squeeze_fraction	number		Fraction of `max_scratchpad_size` at which `compact_history` also auto-squeezes the scratchpad. Default 0.95 — leaving 5% headroom keeps the next tool call from immediately tripping the persistence cap.
signing_schemes	string[]		Signing schemes this agent supports (placeholder for #115). Values will be validated against `SigningScheme` enum when implemented. Empty means no signing support (legacy/internal agent).
supports_native_thinking	boolean
system_prompt_override	string \| null
task_precision	object \| null		Per-task-category precision parameters for the thermodynamic model. Map from task category (e.g. "supply", "audit", "quant", "legal") to `{ pg, pv }` where pg = zero-shot generation precision, pv = verification precision. Used by the dashboard to compute the NSED utility function: U(t) = 1 - (1-pg) * exp(-Lambda(pv-pg)t) - beta*t^2 If absent, the dashboard falls back to built-in MODEL_PRECISION defaults.
temperature	number
textual_feedback	boolean
tool_format	string \| null
unwrap_hallucinated_tool_calls	boolean
use_streaming	boolean

404Agent not found

GET /api/agents/{name}/status per-agent status.

path parameters

name

string

required

Agent name

Responses

200Agent status snapshotAgentStatusSnapshot

field	type		description
agent_id	string	required
buffered_count	integer	required	Number of responses currently held in the HITL buffer.
current_job	string \| null
current_phase	string \| null		Current deliberation phase: `"propose"`, `"evaluate"`, or `null`.
current_round	integer \| null
error_rate	number	required	Rolling error rate: `tasks_failed / (tasks_completed + tasks_failed)`.
event_log	EventLogEntry[]	required	Chronological event log for the dashboard event stream.
flag_reason	string \| null		Human-readable reason why the agent is flagged.
is_flagged	boolean	required	Whether the agent is flagged for operator attention.
is_paused	boolean	required	Whether the agent is paused (HITL control plane).
mean_score	number \| null		Rolling mean of `recent_scores`. `None` if no scores received yet.
model_name	string	required
nats_connected	boolean	required
provider_id	string	required
recent_scores	ScoreEntry[]	required	Recent peer evaluation scores received from the orchestrator. Primary divergence indicator — consistently low scores flag a problem.
recent_tasks	TaskLogEntry[]	required
score_std_dev	number \| null		Standard deviation of recent scores — higher values indicate divergence.
scratchpad_keys	integer	required
tasks_completed	integer	required
tasks_failed	integer	required
uptime_secs	integer	required

404Agent not found

HITL

PUT /api/agents/auto-all enable or disable auto-approve for all agents.

Request body AutoApproveRequest

field	type		description
enabled	boolean	required
threshold	number \| null		Divergence threshold (0.0 to 1.0). Optional — if absent, only the enabled flag is updated.

Responses

200Auto-approve updated for all agents

400Invalid threshold value

PUT /api/agents/pause-all pause or resume all agents at once.

Request body PauseRequest

field	type		description
paused	boolean	required

Responses

200All agents paused/resumed

PUT /api/agents/{name}/auto set auto-approve mode for an agent.

When auto-approve is enabled and the agent's effective divergence score falls below the configured threshold, buffered responses are auto-released immediately instead of waiting for the hold timer.

path parameters

name

string

required

Agent name

Request body AutoApproveRequest

field	type		description
enabled	boolean	required
threshold	number \| null		Divergence threshold (0.0 to 1.0). Optional — if absent, only the enabled flag is updated.

Responses

200Auto-approve state updated

400Invalid threshold value

404Agent or buffer not found

GET /api/agents/{name}/buffer list buffered responses.

Automatically drains entries from previous jobs when the agent has moved on to a new job, preventing stale evaluations from cluttering the review queue.

path parameters

name

string

required

Agent name

Responses

200List of buffered entriesBufferEntrySummary[]

404Agent not found

GET /api/agents/{name}/buffer/{id} get full detail of a buffer entry.

Returns the deserialized response content (Proposal or Evaluation JSON) along with summary metadata. Used by the dashboard for operator inspection and editing before release.

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Responses

200Buffer entry detailBufferEntryDetail

404Agent or entry not found

PUT /api/agents/{name}/buffer/{id} edit a buffered response's content.

Creates an OperatorAnnotation for audit traceability. If content is provided, the payload is replaced and the annotation type is Edit. If only operator_comment is provided, the annotation type is Comment.

When the operator edits the response, they become the "owner" of that output (in the future this will replace the agent's digital signature with the operator's higher-order key).

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Request body BufferEditRequest

field	type		description
content	object		Modified response content (Proposal or Evaluation JSON). If `None`, only the operator comment is recorded (no content change).
operator_comment	string \| null		Optional operator commentary.

Responses

200Buffer entry edited

400Invalid content or missing fields

404Agent or entry not found

POST /api/agents/{name}/buffer/{id}/reject discard a buffer entry.

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Responses

200Entry rejected and discarded

404Agent or entry not found

POST /api/agents/{name}/buffer/{id}/release force-release a buffer entry.

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Responses

200Entry marked for release

404Agent or entry not found

POST /api/agents/{name}/buffer/{id}/stop reversibly stop a buffer entry.

Stopped entries remain in the buffer but are skipped by drain_ready(). The operator can later un-stop the entry to make it eligible for release.

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Responses

200Entry stopped

404Agent or entry not found

POST /api/agents/{name}/buffer/{id}/unstop un-stop a previously stopped entry.

The entry becomes eligible for drain_ready() again. If its release_at has already passed, it will drain on the next worker cycle (≤500ms).

path parameters

name	string	required	Agent name
id	string	required	Buffer entry ID

Responses

200Entry un-stopped

404Agent or entry not found

PUT /api/agents/{name}/config live-update tunable parameters.

Applies a [ConfigPatch] — only non-null fields are updated. Changes are in-memory only (lost on restart).

path parameters

name

string

required

Agent name

Request body ConfigPatch

field	type		description
frequency_penalty	number \| null
max_react_iterations	integer \| null
max_retries	integer \| null
persona	string \| null
presence_penalty	number \| null
temperature	number \| null
textual_feedback	boolean \| null

Responses

200Config patched successfully

400Invalid config patch

404Agent not found

PUT /api/agents/{name}/pause pause or resume an agent.

Toggles the worker's pause flag via its AtomicBool handle. This works regardless of whether a response buffer is configured. When a buffer is also present, its pause flag is toggled in tandem.

path parameters

name

string

required

Agent name

Request body PauseRequest

field	type		description
paused	boolean	required

Responses

200Pause state updated

404Agent not found

Chat

POST /api/agents/{name}/chat chat with a specific agent.

path parameters

name

string

required

Agent name

Request body ChatRequest

field	type		description
messages	ChatMessage[]	required

Responses

200Chat response from the agentChatResponse

field	type		description
response	string	required

400Invalid chat request payloadChatResponse

field	type		description
response	string	required

404Agent not foundChatResponse

field	type		description
response	string	required

500LLM call failedChatResponse

field	type		description
response	string	required

Config

GET /api/config return global configuration (base hold duration).

Responses

200Current global configurationGlobalConfig

field	type		description
base_hold_secs	integer	required
buffer_floor_pct	integer	required	Buffer floor as % of total SLA — minimum hold before divergence boost.
response_sla_secs	integer	required	Global response SLA in seconds — agents exceeding this are flagged.

PUT /api/config update global configuration.

When base_hold_secs changes, all agent buffers' base hold duration is updated to the new value.

Request body GlobalConfigUpdate

field	type		description
base_hold_secs	integer \| null
buffer_floor_pct	integer \| null
response_sla_secs	integer \| null

Responses

200Updated global configurationGlobalConfig

field	type		description
base_hold_secs	integer	required
buffer_floor_pct	integer	required	Buffer floor as % of total SLA — minimum hold before divergence boost.
response_sla_secs	integer	required	Global response SLA in seconds — agents exceeding this are flagged.

Registry

GET /api/orchestrators list active orchestrator connections.

Responses

200List of active orchestrator connectionsActiveOrchestrator[]

POST /api/orchestrators request adding a new orchestrator at runtime.

The request is forwarded to the runner via a channel. The actual registration (JWT ceremony) and worker spawning happens asynchronously.

Request body AddOrchestratorRequest

field	type		description
agent_names	string[]		Optional list of agent names to connect. If empty, all agents connect.
bearer_token	string \| null		Bearer token for authentication (supports `${ENV_VAR}` expansion).
id	string \| null		Optional orchestrator ID. Derived from URL hostname if omitted.
url	string	required	Orchestrator HTTP URL (e.g. "http://orch-2:8080").

Responses

202Orchestrator registration queued

400Invalid request

503Orchestrator registry not available

GET /api/orchestrators/budgets fetch budget from each connected orchestrator.

For each orchestrator, proxies GET /api/operators/budget using the stored bearer token. Returns an array of results (one per orchestrator).

Responses

200Budget info per orchestratorOrchestratorBudget[]

Agent Management

POST /api/agents/bulk Bulk register agents

Request body BulkRegisterRequest

field	type		description
agents	RegisterAgentRequest[]	required

Responses

202Agent registrations accepted (pending hot-reload)BulkRegisterResponse

field	type
errors	string[]	required
failed	integer	required
registered	string[]	required

POST /api/agents/register Register new agent

Add a new agent to the config and start it. Returns 409 if the agent already exists.

Request body RegisterAgentRequest

field	type		description
capability_tags	string[]		Capability tags for directory filtering.
description	string \| null		Agent description.
model_name	string \| null		Model name (optional for stub provider).
name	string	required	Unique agent name (alphanumeric + underscore, max 64 chars).
persona	string \| null		Agent persona / system prompt.
provider_id	string	required	Provider ID — must reference a configured provider.
response_sla_secs	integer \| null		Response SLA in seconds.
signing_schemes	string[]		Signing schemes supported.

Responses

202Agent registration accepted (pending hot-reload)RegisterAgentResponse

field	type		description
name	string	required
status	string	required

400Invalid agent name or config

409Agent already exists

PUT /api/agents/{id}/manage Replace agent config

Full replace of agent configuration in memory. Config changes take effect on the worker's next task cycle. Full restart requires AgentManager integration.

path parameters

string

required

Agent ID (currently name; future: pubkey fingerprint)

Request body RegisterAgentRequest

field	type		description
capability_tags	string[]		Capability tags for directory filtering.
description	string \| null		Agent description.
model_name	string \| null		Model name (optional for stub provider).
name	string	required	Unique agent name (alphanumeric + underscore, max 64 chars).
persona	string \| null		Agent persona / system prompt.
provider_id	string	required	Provider ID — must reference a configured provider.
response_sla_secs	integer \| null		Response SLA in seconds.
signing_schemes	string[]		Signing schemes supported.

Responses

200Agent updatedRegisterAgentResponse

field	type		description
name	string	required
status	string	required

400Invalid config

404Agent not found

PATCH /api/agents/{id}/manage Patch agent config

Partial update — only provided fields are changed.

path parameters

string

required

Agent ID (currently name; future: pubkey fingerprint)

Request body PatchAgentRequest

field	type		description
capability_tags	array \| null
description	string \| null
model_name	string \| null
persona	string \| null
provider_id	string \| null
response_sla_secs	integer \| null
signing_schemes	array \| null

Responses

200Agent patchedRegisterAgentResponse

field	type		description
name	string	required
status	string	required

404Agent not found

DELETE /api/agents/{id}/manage Remove agent

Stop and remove an agent. Use ?force=true to remove agents with pending tasks.

path parameters

string

required

Agent ID (currently name; future: pubkey fingerprint)

query parameters

force

boolean

Set to true to force removal of agents with pending tasks

Responses

202Agent removal accepted (pending hot-reload)

404Agent not found

409Agent has pending tasks (use ?force=true)