REST API
Complete HTTP endpoint reference for the AgentField control plane.
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/discoverReturns 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/queryQuery 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/queryBatch Operations
POST /api/v1/agentic/batchCombine 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
}
}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]'