Agent API

Reference for the local Toolang agent HTTP API.

Base URL for a running local agent is http://127.0.0.1:<port> unless the agent is started with a different host or port.

Endpoints

Agent

Agent profile, health, and operational update endpoints.

List Agent Agics

GET /api/v1/agics

Responses:

List Agent Flows

GET /api/v1/flows

Responses:

List Agent Models

GET /api/v1/models

Parameters:

Responses:

Get Profile

GET /api/v1/profile

Responses:

List Prompt Completions

GET /api/v1/prompt-completions

Parameters:

Responses:

List Agent Tools

GET /api/v1/tools

Parameters:

Responses:

Health Check

GET /healthz

Responses:

Caps

Capability inspection and mutation endpoints.

Get Caps Summary

GET /api/v1/caps

Parameters:

Responses:

List Prompts

GET /api/v1/prompts

Parameters:

Responses:

List Prompt Templates

GET /api/v1/prompts/templates

Responses:

Get Prompt Template

GET /api/v1/prompts/templates/{template_name}

Parameters:

Responses:

Get Prompt

GET /api/v1/prompts/{name}

Parameters:

Responses:

List Psyches

GET /api/v1/psyches

Parameters:

Responses:

List Psyche Templates

GET /api/v1/psyches/templates

Responses:

Get Psyche Template

GET /api/v1/psyches/templates/{template_name}

Parameters:

Responses:

Get Psyche

GET /api/v1/psyches/{name}

Parameters:

Responses:

List Services

GET /api/v1/services

Parameters:

Responses:

List Service Templates

GET /api/v1/services/templates

Responses:

Get Service Template

GET /api/v1/services/templates/{template_name}

Parameters:

Responses:

Get Service

GET /api/v1/services/{name}

Parameters:

Responses:

List Skills

GET /api/v1/skills

Parameters:

Responses:

List Skill Templates

GET /api/v1/skills/templates

Responses:

Get Skill Template

GET /api/v1/skills/templates/{template_name}

Parameters:

Responses:

Get Skill

GET /api/v1/skills/{name}

Parameters:

Responses:

Upsert Authored Prompt

PUT /api/v1/prompts/{name}/authored

Parameters:

Request body:

Responses:

Configure Prompt

PUT /api/v1/prompts/{name}/configured

Parameters:

Request body:

Responses:

Upsert Authored Psyche

PUT /api/v1/psyches/{name}/authored

Parameters:

Request body:

Responses:

Configure Psyche

PUT /api/v1/psyches/{name}/configured

Parameters:

Request body:

Responses:

Upsert Authored Service

PUT /api/v1/services/{name}/authored

Parameters:

Request body:

Responses:

Configure Service

PUT /api/v1/services/{name}/configured

Parameters:

Request body:

Responses:

Upsert Authored Skill

PUT /api/v1/skills/{name}/authored

Parameters:

Request body:

Responses:

Configure Skill

PUT /api/v1/skills/{name}/configured

Parameters:

Request body:

Responses:

Delete Authored Prompt

DELETE /api/v1/prompts/{name}/authored

Parameters:

Responses:

Remove Configured Prompt

DELETE /api/v1/prompts/{name}/configured

Parameters:

Responses:

Delete Authored Psyche

DELETE /api/v1/psyches/{name}/authored

Parameters:

Responses:

Remove Configured Psyche

DELETE /api/v1/psyches/{name}/configured

Parameters:

Responses:

Delete Authored Service

DELETE /api/v1/services/{name}/authored

Parameters:

Responses:

Remove Configured Service

DELETE /api/v1/services/{name}/configured

Parameters:

Responses:

Delete Authored Skill

DELETE /api/v1/skills/{name}/authored

Parameters:

Responses:

Remove Configured Skill

DELETE /api/v1/skills/{name}/configured

Parameters:

Responses:

Jobs

Task and chore management endpoints.

List Chores

GET /api/v1/chores

Responses:

List Archived Chores

GET /api/v1/chores/archived

Responses:

Get Archived Chore

GET /api/v1/chores/archived/{chore_id}

Parameters:

Responses:

Get Chore

GET /api/v1/chores/{chore_id}

Parameters:

Responses:

List Jobs

GET /api/v1/jobs

Parameters:

Responses:

List Archived Jobs

GET /api/v1/jobs/archived

Parameters:

Responses:

Get Archived Job

GET /api/v1/jobs/archived/{job_id}

Parameters:

Responses:

Get Job

GET /api/v1/jobs/{job_id}

Parameters:

Responses:

List Tasks

GET /api/v1/tasks

Responses:

List Archived Tasks

GET /api/v1/tasks/archived

Responses:

Get Archived Task

GET /api/v1/tasks/archived/{task_id}

Parameters:

Responses:

Get Task

GET /api/v1/tasks/{task_id}

Parameters:

Responses:

Create Chore

POST /api/v1/chores

Request body:

Responses:

Archive Chore

POST /api/v1/chores/{chore_id}/archive

Parameters:

Responses:

Cancel Chore

POST /api/v1/chores/{chore_id}/cancel

Parameters:

Responses:

Draft Chore

POST /api/v1/chores/{chore_id}/draft

Parameters:

Responses:

Ready Chore

POST /api/v1/chores/{chore_id}/ready

Parameters:

Responses:

Run Chore

POST /api/v1/chores/{chore_id}/run

Parameters:

Responses:

Create Task

POST /api/v1/tasks

Request body:

Responses:

Archive Task

POST /api/v1/tasks/{task_id}/archive

Parameters:

Responses:

Cancel Task

POST /api/v1/tasks/{task_id}/cancel

Parameters:

Responses:

Draft Task

POST /api/v1/tasks/{task_id}/draft

Parameters:

Responses:

Ready Task

POST /api/v1/tasks/{task_id}/ready

Parameters:

Responses:

Reopen Task

POST /api/v1/tasks/{task_id}/reopen

Parameters:

Responses:

Delete Archived Chore

DELETE /api/v1/chores/archived/{chore_id}

Parameters:

Responses:

Delete Archived Task

DELETE /api/v1/tasks/archived/{task_id}

Parameters:

Responses:

Update Archived Chore

PATCH /api/v1/chores/archived/{chore_id}

Parameters:

Request body:

Responses:

Update Chore

PATCH /api/v1/chores/{chore_id}

Parameters:

Request body:

Responses:

Update Archived Task

PATCH /api/v1/tasks/archived/{task_id}

Parameters:

Request body:

Responses:

Update Task

PATCH /api/v1/tasks/{task_id}

Parameters:

Request body:

Responses:

Runs

Run execution and inspection endpoints.

List Runs

GET /api/v1/runs

Parameters:

Responses:

Get Run Defaults

GET /api/v1/runs/defaults

Return concrete defaults for a client-owned run session.

Responses:

Get Run

GET /api/v1/runs/{run_id}

Parameters:

Responses:

Stream Run Events

GET /api/v1/runs/{run_id}/stream

Parameters:

Responses:

Execute Authored Run Stream

POST /api/v1/runs/authored/stream

Request body:

Responses:

Execute Run Stream

POST /api/v1/runs/stream

Request body:

Responses:

Cancel Run

POST /api/v1/runs/{run_id}/cancel

Parameters:

Request body:

Responses:

Rerun Run

POST /api/v1/runs/{run_id}/rerun

Parameters:

Request body:

Responses:

Rerun Authored Run Stream

POST /api/v1/runs/{run_id}/rerun/stream

Parameters:

Request body:

Responses:

Retry Run

POST /api/v1/runs/{run_id}/retry

Parameters:

Request body:

Responses:

Retry Authored Run Stream

POST /api/v1/runs/{run_id}/retry/stream

Parameters:

Request body:

Responses:

Steer Run

POST /api/v1/runs/{run_id}/steer

Parameters:

Request body:

Responses:

Threads

Thread lifecycle and inspection endpoints.

List Threads

GET /api/v1/threads

Parameters:

Responses:

Get Thread

GET /api/v1/threads/{thread_id}

Parameters:

Responses:

Get Latest Thread Result

GET /api/v1/threads/{thread_id}/result

Parameters:

Responses:

Stream Thread Events

GET /api/v1/threads/{thread_id}/stream

Parameters:

Responses:

Create Thread

POST /api/v1/threads

Request body:

Responses:

Fork Thread

POST /api/v1/threads/{thread_id}/fork

Parameters:

Request body:

Responses:

Rewind Thread

POST /api/v1/threads/{thread_id}/rewind

Parameters:

Request body:

Responses:

Schemas

AgentCapResource

Stable identity of one State capability available to an agent.

AgentCeiling

Stable queries that can only narrow agent resources.

AgentResources

Stable ordered resources available at one execution point.

AgentToolResource

Stable identity of one model-facing tool available to an agent.

Array_Value_

One immutable typed Toolang array.

AskStmt

AudioInputPart

One audio input part.

AudioPart

One canonical audio input part.

AuthoredRerunRequest

One unresolved rerun request for server-owned resolution.

AuthoredRetryRequest

One unresolved retry request for server-owned resolution.

AuthoredRunRequest

One materialized authored run request.

CancelControlPayload

Optional run cancellation reason values.

CapDetail

Complete representation of one effective capability.

CapInfo

Summary of one effective capability.

ChoreCreateRequest

Request one authored chore creation.

ChorePatchRequest

Request one authored chore update.

CollectionStepNoted

Collection cardinality learned while executing one Flow Step.

CompactControlPayload

One compact Run output made available for adoption.

ConfiguredCapRequest

One configured cap ref mutation request.

ControlInfo

One accepted execution control.

DocumentInputPart

One document input part.

DocumentPart

One canonical document part.

DropStmt

ExecuteControlPayload

One durable same-Run runnable replacement.

ForkControlPayload

Fork one thread at a visible run.

GatherStmt

ImageInputPart

One image input part.

ImagePart

One canonical image input part.

InputMessagePayload

One user-authored input message.

IterationOccurrence

One loop iteration and the phase executing within it.

JobDetail

Complete representation of one authored job.

JobInfo

Summary of one authored task or chore.

JobRuntimeInfo

Runtime state attached to one authored job.

KeepStmt

LastRunInfo

Small run summary embedded in job runtime state.

LetStmt

LoopStepNoted

Iteration count and terminal cause learned when a loop Step ends.

MapStmt

ModelAccounting

Versioned durable accounting for one completed model call.

ModelCost

One provider-reported or catalog-estimated monetary amount.

ModelCostLine

One applied quantity and rate contributing to a model cost.

ModelOverride

Sparse model identity and typed parameter changes from one input source.

ModelParameters

Typed call parameters attached to one model request.

ModelPricing

Catalog pricing provenance captured for one completed call.

ModelReasoningAccounting

Requested, selected, and provider-reported reasoning controls.

ModelRequest

One exact model ref and its typed call parameters.

ModelStepNoted

Accounting and continuation learned when a model Step ends.

ModelTokenCount

Input and output tokens consumed by one model Step.

ModelTokenPrice

Decimal-text prices applied to one model Step.

ModelUsageMeter

One auditable quantity within model-call accounting.

Occurrence

Runtime position of one Run or Step within structural execution.

OccurrencePosition

One zero-based position within a known total.

Output

One produced local and its optional destination in the local table.

PromptInvocation

One resolved authored prompt invocation and its immutable definition.

PutCapRequest

One authored cap write request.

ReasoningParameters

Reasoning controls requested for one model selection.

RecallControlPayload

One immutable resource revision recalled by the runtime.

ReloadControlPayload

One durable Agent State revision adopted by an active root run.

RepeatStmt

RetryControlPayload

Effective settings and restart boundary for one retry.

RewindControlPayload

Rewind one thread with an optimistic head check.

RulesRecallTarget