REST API

80+ REST API endpoints organized by function

Complete HTTP endpoint reference for the AgentField control plane.

Every AgentField control plane exposes a REST API on its configured port (default 8080). All agent-facing endpoints live under the /api/v1 prefix. All request and response bodies are JSON.

Authentication

Most endpoints require the control plane API key passed as a Bearer token:

Authorization: Bearer <AGENTFIELD_API_KEY>

Admin endpoints require a separate admin token configured via AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN.

Agentic API — AI-Native Endpoints

The Agentic API is what makes AgentField AI-native. These endpoints are designed for AI agents — Claude Code, Cursor, Codex, or any LLM-powered tool — to discover, query, and operate the control plane programmatically. Every response is machine-readable JSON optimized for LLM consumption.

Unlike traditional APIs that assume a human developer reading docs, the Agentic API provides self-describing capabilities, structured queries over platform resources, and batched operations so an AI agent can explore and use the control plane programmatically.

Discovery

GET /api/v1/agentic/discover

Returns a machine-readable catalog of API endpoints from the control plane's internal catalog. AI agents can use this as a first call to understand what the platform can do.

Response:

{
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/v1/agentic/status",
      "summary": "Get system status overview",
      "group": "agentic"
    }
  ],
  "total": 1,
  "groups": ["agentic", "discovery", "memory"],
  "filters": { "q": "", "group": "", "method": "" },
  "see_also": {
    "live_agents": "GET /api/v1/discovery/capabilities",
    "kb": "GET /api/v1/agentic/kb/topics"
  }
}

Example:

curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/agentic/discover | jq '.endpoints[].path'

Structured Resource Query

POST /api/v1/agentic/query

Query platform resources with an explicit resource name plus filters. This is the primary interface for AI agents that need a predictable response shape.

Request:

{
  "resource": "executions",
  "filters": {
    "status": "completed",
    "agent_id": "doc-parser"
  },
  "limit": 10,
  "offset": 0
}

Response:

{
  "resource": "executions",
  "results": [
    {
      "execution_id": "exec_123",
      "status": "completed"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Example:

curl -s -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"agents","limit":5}' \
  http://localhost:8080/api/v1/agentic/query

Batch Operations

POST /api/v1/agentic/batch

Combine multiple API calls into a single request. Reduces round-trips for AI agents that need to perform several operations through one control-plane call.

Request:

{
  "operations": [
    {
      "id": "op1",
      "method": "GET",
      "path": "/api/v1/nodes"
    },
    {
      "id": "op2",
      "method": "POST",
      "path": "/api/v1/memory/get",
      "body": { "key": "session:current", "namespace": "global" }
    },
    {
      "id": "op3",
      "method": "POST",
      "path": "/api/v1/execute/planner.analyze",
      "body": { "input": { "topic": "quarterly review" } }
    }
  ]
}

Response:

{
  "results": [
    { "id": "op1", "status": 200, "body": { "nodes": ["..."] } },
    { "id": "op2", "status": 200, "body": { "value": "sess_abc123" } },
    { "id": "op3", "status": 200, "body": { "execution_id": "exec_7f3a", "status": "completed", "result": {"...": "..."} } }
  ],
  "total": 3
}

Run and Agent Summary

Method	Endpoint	Description	Auth
GET	`/api/v1/agentic/run/:run_id`	Get overview of a workflow run including step statuses	Yes
GET	`/api/v1/agentic/agent/:agent_id/summary`	Get agent summary: capabilities, recent executions, health	Yes
GET	`/api/v1/agentic/status`	Platform status summary: node count, memory usage, uptime	Yes

Example — agent summary:

curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/agentic/agent/email-assistant/summary

{
  "agent_id": "email-assistant",
  "status": "online",
  "uptime_seconds": 84720,
  "capabilities": ["draft", "send", "search"],
  "recent_executions": {
    "total_24h": 142,
    "success_rate": 0.97,
    "avg_duration_ms": 1230
  },
  "memory_usage": {
    "kv_keys": 38,
    "vector_count": 1024
  }
}

Agentic Resource Discovery (ARD)

Agentic Resource Discovery exposes selected AgentField reasoners and skills through a public catalog and lets operators import external entries into the control plane. See Expose agents to external discovery for the operator flow.

ARD routes are intentionally split. Public routes expose only published catalog data. UI/admin routes store runtime decisions such as per-reasoner publishing, imported external entries, callable bindings, and registry records.

Public Catalog

GET /.well-known/ai-catalog.json

Returns the public Agentic Resource Discovery catalog when agentfield.ard.enabled, agentfield.ard.publish.enabled, and runtime publishing are enabled.

curl https://control-plane.example.com/.well-known/ai-catalog.json | jq '.entries'

Public ARD Registry Routes

These routes are under the normal API prefix:

Method	Endpoint	Description
GET	`/api/v1/ard/artifacts/:entryID`	Fetch the generated artifact for a published entry, usually OpenAPI JSON.
POST	`/api/v1/ard/search`	Search published catalog entries.
GET	`/api/v1/ard/agents`	List published catalog entries using registry-style pagination.
POST	`/api/v1/ard/explore`	Explore catalog facets and available entry metadata.

Example search:

curl -s -X POST https://control-plane.example.com/api/v1/ard/search \
  -H "Content-Type: application/json" \
  -d '{"query":{"text":"contract review"},"pageSize":10}' | jq '.results'

UI Runtime State

Authenticated UI routes live under /api/ui/v1/ard:

Method	Endpoint	Description
GET	`/api/ui/v1/ard`	Discovery dashboard: config, summary, catalog preview, publications, imports, registries.
PUT	`/api/ui/v1/ard/settings`	Save runtime ARD settings where they are not locked by config.
PUT	`/api/ui/v1/ard/publications`	Save one reasoner/skill publication and metadata.
POST	`/api/ui/v1/ard/external/search`	Search configured external ARD registries.
POST	`/api/ui/v1/ard/imports`	Import one external ARD entry.
PUT	`/api/ui/v1/ard/imports/:entryID/binding`	Configure whether an imported entry is callable as an `external.*` target.
PUT	`/api/ui/v1/ard/registries`	Save known registry records.

Callable external entries use the same execution API as local targets:

curl -s -X POST http://localhost:8080/api/v1/execute/external.vendor.review_contract \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"contract_text":"..."}}'

The call succeeds only when agentfield.ard.external.invocation_enabled is true and the imported entry has an enabled callable binding.

Knowledge Base

The knowledge base provides self-serve documentation endpoints that AI agents can query to learn how to use the platform without external docs.

Method	Endpoint	Description	Auth
GET	`/api/v1/agentic/kb/topics`	List knowledge base topics	No
GET	`/api/v1/agentic/kb/articles`	List knowledge base articles	No
GET	`/api/v1/agentic/kb/articles/:article_id`	Get a specific article	No
GET	`/api/v1/agentic/kb/guide`	Get the quick-start guide	No

Example — get the quick-start guide:

curl -s http://localhost:8080/api/v1/agentic/kb/guide | jq '.title, .steps[0]'

Session Endpoints

Execution Endpoints

Approval (Human-in-the-Loop)

Node Registration and Lifecycle

Memory Endpoints

Discovery, Health, DID, Workflow

Admin, Config, Observability

On this page