REST API

Sessions

Sessions are realtime or multimodal entrypoints declared by SDK agents and started through the control plane.

Start a Session

POST /api/v1/session-targets/:target/start

target uses <node_id>.<session_name>.

Request:

{
  "provider": "openai",
  "transport": "webrtc",
  "model": "gpt-realtime-2",
  "voice": "marin"
}

Response:

{
  "session_id": "sess_123",
  "target": "voice-support-af.voice",
  "provider": "openai",
  "transport": "webrtc",
  "offer_url": "/api/v1/session-instances/sess_123/realtime-offer",
  "tool_url": "/api/v1/session-instances/sess_123/tools/{tool}",
  "tool_targets": {
    "voice-support-af.resolve_voice_turn": "voice-support-af.resolve_voice_turn"
  },
  "tags": ["support:voice"]
}

Exchange Realtime Offer

POST /api/v1/session-instances/:session_id/realtime-offer?provider=openai&transport=webrtc

For WebRTC, send the SDP offer as application/sdp; the response body is the SDP answer.

curl -s -X POST \
  "http://localhost:8080/api/v1/session-instances/sess_123/realtime-offer?provider=openai&transport=webrtc" \
  -H "Content-Type: application/sdp" \
  --data-binary @offer.sdp > answer.sdp

Invoke a Session Tool

POST /api/v1/session-instances/:session_id/tools/:tool

This endpoint is for provider/client-driven tool calls during a live session. Handler-controlled orchestration should use the SDK's session.call(...) or normal app.call(...) path.

Request:

{
  "target": "voice-support-af.resolve_voice_turn",
  "input": {
    "turn": {
      "transcript": "My order has not arrived."
    }
  }
}

The control plane forwards the tool call to execute/async with the session ID attached. That keeps provider-driven reasoner work visible in normal AgentField workflow views.

Provider and transport are explicit. AgentField validates the pair and does not infer or switch providers.

Execution

Synchronous Execution

POST /api/v1/execute/:target

Execute a reasoner or skill synchronously. The target is formatted as agent.reasoner_id or agent.skill_id.

Request:

{
  "input": {
    "prompt": "Summarize the Q4 earnings report",
    "max_tokens": 2000
  },
  "context": {
    "session_id": "sess_123"
  },
  "webhook": {
    "url": "https://example.com/agentfield-webhook"
  }
}

Response (200):

{
  "execution_id": "exec_8f2a1b3c",
  "run_id": "run_8f2a1b3c",
  "status": "completed",
  "result": {
    "summary": "Q4 revenue grew 23% year-over-year...",
    "confidence": 0.92
  },
  "duration_ms": 2340,
  "finished_at": "2026-03-24T10:15:12Z",
  "webhook_registered": false
}

Error Response (400):

{
  "error": "invalid_target",
  "message": "Target 'summarizer.nonexistent' not found. Available targets: summarizer.analyze, summarizer.extract",
  "available_targets": ["summarizer.analyze", "summarizer.extract"]
}

Example:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Summarize the Q4 report"}}' \
  http://localhost:8080/api/v1/execute/summarizer.analyze

Asynchronous Execution

POST /api/v1/execute/async/:target

Queue an execution and return immediately with an execution_id. Use the status endpoint to poll for results.

Request: Same as synchronous execution.

Response (202):

{
  "execution_id": "exec_c94d2e1f",
  "run_id": "run_c94d2e1f",
  "workflow_id": "run_c94d2e1f",
  "status": "queued",
  "target": "doc-parser.extract",
  "type": "reasoner",
  "created_at": "2026-03-24T10:15:00Z",
  "webhook_registered": false
}

Example:

# Start async execution
EXEC_ID=$(curl -s -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"document_url": "s3://bucket/large-report.pdf"}}' \
  http://localhost:8080/api/v1/execute/async/doc-parser.extract \
  | jq -r '.execution_id')

# Poll for result
curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/executions/$EXEC_ID

Legacy aliases (kept for backward compatibility):

Execution Status and Lifecycle

Get Execution Status

GET /api/v1/executions/:execution_id

Response:

{
  "execution_id": "exec_c94d2e1f",
  "run_id": "run_c94d2e1f",
  "status": "completed",
  "result": { "pages": 42, "text": "..." },
  "started_at": "2026-03-24T10:15:00Z",
  "completed_at": "2026-03-24T10:15:12Z",
  "duration_ms": 12340,
  "webhook_registered": false
}

Status values: queued, running, completed, failed, cancelled, paused.

Batch Status

POST /api/v1/executions/batch-status

Request:

{
  "execution_ids": ["exec_c94d2e1f", "exec_a1b2c3d4", "exec_e5f6g7h8"]
}

Response:

{
  "exec_c94d2e1f": { "execution_id": "exec_c94d2e1f", "status": "completed" },
  "exec_a1b2c3d4": { "execution_id": "exec_a1b2c3d4", "status": "running" },
  "exec_e5f6g7h8": { "execution_id": "exec_e5f6g7h8", "status": "failed", "error": "Node offline" }
}

Lifecycle Operations

Example — cancel an execution:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/executions/exec_c94d2e1f/cancel

Response:

{
  "execution_id": "exec_c94d2e1f",
  "status": "cancelled",
  "cancelled_at": "2025-03-24T10:16:00Z"
}

Execution Notes

Attach notes to an execution for audit trails, debugging, or inter-agent communication.

POST /api/v1/executions/note

Request:

{
  "message": "Retrying with increased timeout due to large document size",
  "tags": ["retry", "debug"]
}

Provide the execution ID via the active execution context, the X-Execution-ID header, or a query parameter.

GET /api/v1/executions/:execution_id/notes

Response:

{
  "execution_id": "exec_c94d2e1f",
  "notes": [
    {
      "id": "note_1a2b3c",
      "note": "Retrying with increased timeout due to large document size",
      "author": "orchestrator-agent",
      "created_at": "2025-03-24T10:15:30Z"
    }
  ]
}

Approval

Human-in-the-loop approval allows agents to pause execution and request human sign-off before proceeding with sensitive operations.

Request Approval

POST /api/v1/agents/:node_id/executions/:execution_id/request-approval

Request:

{
  "approval_request_id": "req-123",
  "approval_request_url": "https://internal.example.com/approvals/req-123",
  "callback_url": "https://your-app.com/webhooks/approval"
}

Response (202):

{
  "approval_request_id": "req-123",
  "approval_request_url": "https://internal.example.com/approvals/req-123"
}

Check Approval Status

GET /api/v1/agents/:node_id/executions/:execution_id/approval-status

Response:

{
  "status": "approved",
  "response": {
    "decision": "approved",
    "feedback": "Approved - batch is expected"
  },
  "request_url": "https://internal.example.com/approvals/req-123",
  "requested_at": "2026-03-24T10:15:00Z",
  "responded_at": "2026-03-24T10:20:00Z"
}

Status values: pending, approved, rejected, expired.

Agent-Scoped Approval

For multi-agent setups, scope approval requests to a specific agent node:

External Approval Webhook

POST /api/v1/webhooks/approval-response

Receive approval decisions from external systems (Slack bots, email links, custom UIs).

Request:

{
  "requestId": "req-123",
  "decision": "approved",
  "feedback": "Looks good, proceed"
}

Example — full approval flow:

# 1. Request approval
curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approval_request_id":"req-123","expires_in_hours":1}' \
  http://localhost:8080/api/v1/agents/my-agent/executions/exec_c94d2e1f/request-approval

# 2. Check status (poll or use webhook)
curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/agents/my-agent/executions/exec_c94d2e1f/approval-status

# 3. Once approved, resume the execution
curl -X POST -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/executions/exec_c94d2e1f/resume

Node Registration

Agent nodes register with the control plane on startup and maintain their presence via heartbeats.

Register a Node

POST /api/v1/nodes/register

Request:

{
  "name": "email-assistant",
  "url": "http://10.0.1.5:8005",
  "capabilities": {
    "reasoners": [
      {
        "id": "draft",
        "description": "Draft an email from a prompt",
        "input_schema": { "type": "object", "properties": { "prompt": { "type": "string" } } },
        "output_schema": { "type": "object", "properties": { "subject": { "type": "string" }, "body": { "type": "string" } } }
      }
    ],
    "skills": [
      {
        "id": "send",
        "description": "Send a drafted email"
      }
    ]
  },
  "tags": ["email", "communication"],
  "metadata": {
    "version": "1.2.0",
    "language": "python"
  }
}

Response (201):

{
  "node_id": "node_a1b2c3d4",
  "name": "email-assistant",
  "status": "online",
  "registered_at": "2025-03-24T10:00:00Z",
  "heartbeat_interval_seconds": 30
}

Error Response (409):

{
  "error": "node_already_registered",
  "message": "Node 'email-assistant' is already registered. Use PUT to update or DELETE to unregister first.",
  "existing_node_id": "node_a1b2c3d4"
}

Example:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "url": "http://localhost:8005",
    "capabilities": {"reasoners": [], "skills": []}
  }' \
  http://localhost:8080/api/v1/nodes/register

Other Registration Endpoints

Heartbeat

POST /api/v1/nodes/:node_id/heartbeat

Nodes must send heartbeats at the interval specified during registration. Missed heartbeats mark the node as unhealthy after 3 missed intervals.

Request:

{
  "status": "healthy",
  "load": {
    "active_executions": 2,
    "queue_depth": 5,
    "cpu_percent": 45.2,
    "memory_mb": 512
  }
}

Response (200):

{
  "acknowledged": true,
  "next_heartbeat_seconds": 30
}

Example:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "healthy", "load": {"active_executions": 0}}' \
  http://localhost:8080/api/v1/nodes/node_a1b2c3d4/heartbeat

Node Status

GET status response:

{
  "node_id": "node_a1b2c3d4",
  "name": "email-assistant",
  "status": "online",
  "last_heartbeat": "2025-03-24T10:14:30Z",
  "uptime_seconds": 84720,
  "load": {
    "active_executions": 2,
    "queue_depth": 5
  }
}

Node Lifecycle

Example — graceful shutdown:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/nodes/node_a1b2c3d4/shutdown

{
  "node_id": "node_a1b2c3d4",
  "status": "shutting_down",
  "draining_executions": 2,
  "estimated_drain_seconds": 15
}

Versioned Routing and Traffic Weights

When multiple healthy agents register with the same node_id and different version values, the normal execution endpoint routes across them by traffic_weight. Callers keep using the same target:

POST /api/v1/execute/:target

Example:

curl -i -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Summarize this rollout."}}' \
  http://localhost:8080/api/v1/execute/summarizer.summarize

The response includes the selected version when versioned routing is used:

X-Routed-Version: 3.0.0

Connector routes let deployment tooling inspect versions and adjust weights:

Example -- set a 90/10 split:

curl -X PUT -H "X-Connector-Token: $AGENTFIELD_CONNECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weight": 90}' \
  http://localhost:8080/api/v1/connector/reasoners/summarizer/versions/2.0.0/weight

curl -X PUT -H "X-Connector-Token: $AGENTFIELD_CONNECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weight": 10}' \
  http://localhost:8080/api/v1/connector/reasoners/summarizer/versions/3.0.0/weight

Memory

AgentField provides two memory primitives: a key-value store for structured data and a vector store for semantic search.

Key-Value Store

Set a Value

POST /api/v1/memory/set

Request:

{
  "key": "user:preferences:u123",
  "data": {
    "theme": "dark",
    "language": "en",
    "notifications": true
  },
  "scope": "session"
}

Response (200):

{
  "key": "user:preferences:u123",
  "data": {
    "theme": "dark",
    "language": "en",
    "notifications": true
  },
  "scope": "session",
  "scope_id": "sess_abc123",
  "created_at": "2025-03-24T10:15:00Z",
  "updated_at": "2025-03-24T10:15:00Z"
}

Get a Value

POST /api/v1/memory/get

Request:

{
  "key": "user:preferences:u123",
  "scope": "session"
}

Response (200):

{
  "data": {
    "theme": "dark",
    "language": "en",
    "notifications": true
  },
  "scope": "session",
  "scope_id": "sess_abc123",
  "created_at": "2025-03-24T10:15:00Z",
  "updated_at": "2025-03-24T10:15:00Z"
}

Error Response (404):

{
  "error": "key_not_found",
  "message": "Key 'user:preferences:u123' not found in scope 'session'"
}

Delete and List

Example — list keys in a scope:

curl -s -H "Authorization: Bearer $AF_KEY" \
  "http://localhost:8080/api/v1/memory/list?scope=session"

[
  {
    "scope": "session",
    "scope_id": "sess_abc123",
    "key": "user:preferences:u123",
    "data": {"theme": "dark", "language": "en"},
    "created_at": "2025-03-24T10:15:00Z",
    "updated_at": "2025-03-24T10:15:00Z"
  },
  {
    "scope": "session",
    "scope_id": "sess_abc123",
    "key": "user:cart:u123",
    "data": {"items": 3},
    "created_at": "2025-03-24T09:30:00Z",
    "updated_at": "2025-03-24T10:00:00Z"
  }
]

Vector Store

Store a Vector

POST /api/v1/memory/vector

Request:

{
  "key": "doc:quarterly-report-q4",
  "embedding": [0.023, -0.118, 0.452, 0.007, -0.331],
  "scope": "workflow",
  "metadata": {
    "source": "earnings-report-2024.pdf",
    "page": 3,
    "section": "executive_summary"
  }
}

Response (200):

{
  "key": "doc:quarterly-report-q4",
  "scope": "workflow",
  "dimensions": 1536,
  "created": true
}

Similarity Search

POST /api/v1/memory/vector/search

Request:

{
  "query_embedding": [0.019, -0.105, 0.438, 0.012, -0.298],
  "scope": "workflow",
  "top_k": 5,
  "filters": {
    "source": "earnings-report-2024.pdf"
  }
}

Response (200):

{
  "results": [
    {
      "key": "doc:quarterly-report-q4",
      "content": "Q4 revenue grew 23% year-over-year driven by enterprise expansion...",
      "score": 0.94,
      "metadata": {
        "source": "earnings-report-2024.pdf",
        "page": 3,
        "section": "executive_summary"
      }
    },
    {
      "key": "doc:quarterly-report-q3",
      "content": "Q3 showed 18% growth with strong SMB adoption...",
      "score": 0.78,
      "metadata": {
        "source": "earnings-report-2024.pdf",
        "page": 12
      }
    }
  ],
  "total": 2,
  "query_embedding_dimensions": 1536
}

Example:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query_embedding": [0.019, -0.105, 0.438, 0.012, -0.298], "scope": "workflow", "top_k": 3}' \
  http://localhost:8080/api/v1/memory/vector/search

Other Vector Operations

Memory Events

Subscribe to real-time memory changes for reactive agent architectures.

SSE event format:

event: message
data: {"type": "set", "key": "user:preferences:u123", "scope": "session", "scope_id": "sess_abc123", "action": "set", "timestamp": "2025-03-24T10:15:00Z"}

Example — subscribe via SSE:

curl -s -N -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/memory/events/sse

Health and Metrics

Example:

curl -s http://localhost:8080/health

{
  "status": "ok",
  "version": "0.9.2",
  "uptime_seconds": 86400
}

Discovery

GET /api/v1/discovery/capabilities

List all registered reasoners, skills, and their schemas. Unlike the Agentic API's /discover endpoint, this returns the raw capability registry without AI-friendly annotations.

Response:

{
  "capabilities": [
    {
      "node_id": "node_a1b2c3d4",
      "name": "email-assistant",
      "reasoners": [
        {
          "id": "email-assistant.draft",
          "input_schema": { "type": "object", "properties": { "prompt": { "type": "string" } } }
        }
      ],
      "skills": [
        { "id": "email-assistant.send" }
      ]
    }
  ]
}

Example:

curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/discovery/capabilities | jq '.capabilities[].name'

Workflow

POST /api/v1/workflow/executions/events

Emit structured events to track multi-step workflow progress.

Request:

{
  "workflow_id": "wf_pipeline_001",
  "execution_id": "exec_c94d2e1f",
  "event": "step_completed",
  "step": "data_extraction",
  "data": {
    "records_extracted": 1500,
    "next_step": "validation"
  }
}

Response (200):

{
  "event_id": "evt_x1y2z3",
  "acknowledged": true
}

DID and Verifiable Credentials

Decentralized Identity (DID) and Verifiable Credentials (VC) provide cryptographic identity and capability attestation for agents.

Example — resolve an agent's DID document:

curl -s http://localhost:8080/agents/email-assistant/did.json

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:web:localhost:agents:email-assistant",
  "verificationMethod": [
    {
      "id": "did:web:localhost:agents:email-assistant#key-1",
      "type": "Ed25519VerificationKey2020",
      "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..."
    }
  ],
  "service": [
    {
      "id": "#agentfield",
      "type": "AgentFieldNode",
      "serviceEndpoint": "http://localhost:8005"
    }
  ]
}

Admin Endpoints

Tag Approval

Agents request tags that describe their capabilities. Admins approve or reject these tags before they become part of the agent's discoverable profile.

Example — approve tags:

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved_tags": ["email", "communication"]}' \
  http://localhost:8080/api/v1/admin/agents/email-assistant/approve-tags

Response:

{
  "success": true,
  "message": "Agent tags approved",
  "agent_id": "email-assistant",
  "approved_tags": ["email", "communication"]
}

Access Policies

Define fine-grained access policies that control which agents can execute which capabilities.

Create policy request:

{
  "name": "email-only-verified",
  "description": "Only agents with 'email' tag can execute email-assistant skills",
  "caller_tags": ["email"],
  "target_tags": ["email"],
  "allow_functions": ["email-assistant.send", "email-assistant.draft"],
  "action": "allow",
  "priority": 100
}

Response (201):

{
  "id": 42,
  "name": "email-only-verified",
  "caller_tags": ["email"],
  "target_tags": ["email"],
  "allow_functions": ["email-assistant.send", "email-assistant.draft"],
  "deny_functions": [],
  "constraints": {},
  "action": "allow",
  "priority": 100,
  "enabled": true,
  "description": "Only agents with 'email' tag can execute email-assistant skills",
  "created_at": "2025-03-24T10:00:00Z",
  "updated_at": "2025-03-24T10:00:00Z"
}

Configuration Storage

Runtime configuration key-value store accessible to all agents.

Example — set and get a config value:

# Set
curl -X PUT -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary $'model: claude-sonnet-4-20250514\nmax_tokens: 4096\n' \
  http://localhost:8080/api/v1/configs/default-model

# Get
curl -s -H "Authorization: Bearer $AF_KEY" \
  http://localhost:8080/api/v1/configs/default-model

{
  "key": "default-model",
  "value": "model: claude-sonnet-4-20250514\nmax_tokens: 4096\n",
  "updated_by": "api",
  "created_at": "2025-03-24T10:15:00Z",
  "updated_at": "2025-03-24T10:15:00Z"
}

Response (PUT):

{
  "message": "config saved",
  "config": {
    "key": "default-model",
    "value": "model: claude-sonnet-4-20250514\nmax_tokens: 4096\n",
    "updated_by": "api",
    "created_at": "2025-03-24T10:15:00Z",
    "updated_at": "2025-03-24T10:15:00Z"
  }
}

Observability Webhook

Forward platform events (executions, errors, memory changes) to an external observability system.

Example — configure webhook:

curl -X POST -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhooks/agentfield", "headers": {"X-Webhook-Source": "agentfield"}, "enabled": true}' \
  http://localhost:8080/api/v1/settings/observability-webhook

{
  "success": true,
  "message": "observability webhook configured successfully",
  "config": {
    "id": "global",
    "url": "https://your-app.com/webhooks/agentfield",
    "headers": {
      "X-Webhook-Source": "agentfield"
    },
    "enabled": true,
    "created_at": "2025-03-24T10:15:00Z",
    "updated_at": "2025-03-24T10:15:00Z"
  }
}