REST API

The Agentfleet API is served at https://api.agentfleet.co.za. All endpoints live under /api and require a bearer token from the identity provider; role-based policies apply per operation. Roles follow the agentfleet:<role> naming convention (e.g. agentfleet:workflow-admin, agentfleet:eval-run-admin), and agentfleet:admin is a superuser with all permissions.

This page is a working overview of the most-used endpoints, not an exhaustive contract.

Conventions

• Routes follow api/{controller} (e.g. api/resources, api/workflows, api/workflowinstances, api/evalsuites).
• Mutations take JSON bodies; list endpoints support searchText and status filters, and most also expose a paged variant at /paged?pageNumber=&pageSize=.
• Errors return standard problem responses; validation failures are 400 with per-field detail.

Resources & tools

Method & path	Purpose
POST /api/resources	Register an MCP resource (name, description, baseUrl, path).
POST /api/resources/{id}/import-tools	Discover and upsert the resource's tools. Returns imported/updated counts.
PUT /api/resources/activate / deactivate	Manage the resource lifecycle.
GET /api/tools?resourceId=	List tools (optionally filtered by resource, status, search text).
PUT /api/tools	Update a tool (e.g. correct a scope).

Steps & workflows

Method & path	Purpose
POST /api/steps	Create a step (name, description, instruction, toolId).
POST /api/workflows	Create a workflow (name, description).
POST /api/workflows/steps	Attach a step (workflowId, stepId, order).
PUT /api/workflows/activate / deactivate	Activate a workflow so it can run (or deactivate it).

Runs

Runs are managed through the workflow instances controller.

Method & path	Purpose
PUT /api/workflowinstances/run	Queue a run — workflowId, agentId, optional initialContext (see Run Inputs). Returns 202 with the instance id.
GET /api/workflowinstances/{id}	Run state (Idle/Running/Completed/Failed/Cancelled) and failure reason.
GET /api/workflowinstances/{id}/context	The run's context entries with provenance.
GET /api/workflowinstances/{id}/summary	Aggregate metrics: step progress, tokens, latency, timing.
GET /api/workflowinstances/paged	Page through runs.
PUT /api/workflowinstances/cancel	Request cancellation of a running instance.

Queue a run

curl -X PUT "https://api.agentfleet.co.za/api/workflowinstances/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "agentId": "<agent-id>",
    "initialContext": {
      "task_id": "task-7f3a",
      "purpose": "instance-fulfilment",
      "customerRef": "C-1042"
    }
  }'
# → 202 Accepted { "workflowInstanceId": "…" }

Agents & model providers

Method & path	Purpose
POST /api/agents	Create an agent (registered as a delegated agent with a secretless client).
PUT /api/agents / activate / deactivate	Manage the agent lifecycle.
POST /api/modelproviders	Configure a model provider (models, default model, max tokens).
PUT /api/modelproviders/activate / deactivate	Manage the provider lifecycle.

Automation

Schedules fire a workflow on a cron cadence; event triggers fire it on an inbound Service Bus event. See Automation.

Method & path	Purpose
POST /api/schedules	Create a schedule (workflowId, agentId, cron expression, input template).
PUT /api/schedules	Update a schedule.
PUT /api/schedules/enable / disable	Enable or disable a schedule.
PUT /api/schedules/fire	Fire now — trigger a run on demand. Returns 202.
DELETE /api/schedules	Delete a schedule.
GET /api/schedules/{id} · GET /api/schedules/paged?workflowId=&isEnabled=	Read schedules.
POST /api/eventtriggers	Create an event trigger (workflowId, agentId, event source, event-type filter, input mapping).
PUT /api/eventtriggers · enable · disable · DELETE /api/eventtriggers	Manage the trigger lifecycle.
GET /api/eventtriggers/{id} · GET /api/eventtriggers/paged?workflowId=&isEnabled=	Read event triggers.

Evaluations

Eval suites are managed at api/evalsuites; eval runs at api/evalruns. See Evaluations.

Method & path	Purpose
POST /api/evalsuites	Create a suite (name, description, targetWorkflowId, optional targetStepId, agentId, scoringRubric).
PUT /api/evalsuites	Update a suite (bumps its version).
POST /api/evalsuites/cases	Add a case (evalSuiteId, name, input, optional agentId, method, expectedOutput, passThreshold).
DELETE /api/evalsuites/{id}/cases/{caseId}	Remove a case.
GET /api/evalsuites/{id} · GET /api/evalsuites?searchText=&status=	Read suites (with their cases).
POST /api/evalruns	Start a run — evalSuiteId, optional passThreshold (default 1.0). Returns 202.
GET /api/evalruns/{id}	A run with its per-case results.
GET /api/evalruns?evalSuiteId=	List runs, most-recent first.
GET /api/evalruns/score-trend/{evalSuiteId}	The suite's score-over-time trend.
GET /api/evalruns/{id}/evidence-report	Download the completed run's evidence report as a JSON attachment.

Start an eval run

curl -X POST "https://api.agentfleet.co.za/api/evalruns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "evalSuiteId": "<suite-id>", "passThreshold": 0.8 }'
# → 202 Accepted { "evalRunId": "…" }

Observability

Method & path	Purpose
GET /api/modelcalls?workflowInstanceId=	Model calls for a run (tokens, latency, round, input/output). Also filterable by stepInstanceId; paged.
GET /api/toolcalls?workflowInstanceId=	Tool calls for a run.
GET /api/agentinstances · GET /api/stepinstances	The agent and step instances behind a run.
GET /api/activities/paged	The platform-wide audit activity feed.
GET /api/search?searchText=&limit=	Cross-entity search over agents, steps, tools, resources, and workflows (results are permission-filtered).
GET /health	Unauthenticated health probe (includes a database check).

Run operations

Operational endpoints for the durable run queue, dead-letter recovery, and resuming paused (waiting) instances. Require the agentfleet:run-operations-admin role.

Method & path	Purpose
GET /api/runoperations/queue	Point-in-time run-queue depth by disposition.
GET /api/runoperations/dead-letters	Runs parked in the dead-letter store.
POST /api/runoperations/dead-letters/requeue	Requeue a dead-lettered run. Returns 202.
GET /api/runoperations/paused	Instances paused on a wait step.
POST /api/runoperations/paused/resume	Resume a waiting instance when its wait outcome arrives.