> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the api

# Using the API

Savant exposes two communication channels: the **A2A protocol** (recommended) for agent-to-agent communication, and the **REST API** for administrative operations.

***

## A2A Protocol (Recommended)

The A2A protocol is the primary way to communicate with Savant. It uses JSON-RPC 2.0 over HTTP.

### Send a Message

```bash theme={null}
curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-001",
        "role": "user",
        "parts": [{"kind": "text", "text": "What agents are registered?"}]
      }
    }
  }'
```

### Stream a Response

```bash theme={null}
curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "stream",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-002",
        "role": "user",
        "parts": [{"kind": "text", "text": "Analyze the code in /src"}]
      }
    }
  }'
```

Returns an SSE stream with `TaskStatusUpdateEvent`, `Message`, and `TaskArtifactUpdateEvent` events.

### Invoke a Capability

Send a `DataPart` with the capability name and arguments:

```bash theme={null}
curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-003",
        "role": "user",
        "parts": [{
          "kind": "data",
          "data": {
            "capability": "check_stock",
            "args": {"product_id": "SKU-1234"}
          }
        }]
      }
    }
  }'
```

### Using the SDK (Easier)

The `RemoteAgent` class wraps all of this:

```typescript theme={null}
import { RemoteAgent } from '@svantic/sdk';

const remote = await RemoteAgent.connect('http://localhost:3000');

// Simple message
const answer = await remote.send('What agents are registered?');

// Streaming
for await (const event of remote.send_stream('Analyze the code')) { ... }

// Capability invocation
const result = await remote.invoke_capability('check_stock', { product_id: 'SKU-1234' });
```

***

## REST API

Administrative endpoints for session management, MCP configuration, and guardrails.

### Agent Management

Register requires a JWT from `POST /auth/get_token` (credentials go only there). The register body is `agent_type`, `instance_id`, `url`, and optionally `tools` / `mcp_servers` — not `client_id` / `client_secret`. Success response: `{ "ok": true, "tenant_id": "..." }`.

```bash theme={null}
# 1) Obtain a JWT (client_id / client_secret only here)
TOKEN=$(curl -s -X POST http://localhost:7000/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"acme","client_secret":"secret","agent_type":"my-service"}' \
  | jq -r '.token')

# 2) Register (Bearer token — no credentials in body)
curl -X POST http://localhost:3000/agents/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_type":"my-service","instance_id":"pod-1","url":"http://my-service:4000","tools":[],"mcp_servers":{}}'

# List registered agents
curl -X POST http://localhost:3000/agents/list

# Deregister an agent
curl -X POST http://localhost:3000/agents/deregister \
  -H "Content-Type: application/json" \
  -d '{"agent_type": "my-service", "instance_id": "pod-1"}'
```

### Sessions

```bash theme={null}
# Authenticate first
TOKEN=$(curl -s -X POST http://localhost:7000/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"acme","client_secret":"secret","agent_type":"my-agent"}' \
  | jq -r '.token')

# Create a session (auto-attaches internal agents)
curl -X POST http://localhost:3000/sessions/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"session_id": "sess-001"}'

# Invite a remote agent into the session
curl -X POST http://localhost:3000/sessions/sess-001/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_type": "transcript-link"}'

# Close a session (destroys internal agents, unbinds all)
curl -X POST http://localhost:3000/sessions/sess-001/close \
  -H "Authorization: Bearer $TOKEN"

# List sessions
curl -X POST http://localhost:3000/sessions/list

# Get session history
curl -X POST http://localhost:3000/sessions/get \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess-001"}'
```

### MCP Servers

```bash theme={null}
# Register MCP servers
curl -X POST http://localhost:3000/config/mcp/register \
  -H "Content-Type: application/json" \
  -d '{
    "servers": {
      "chrome-devtools": {
        "command": "npx",
        "args": ["-y", "@anthropic/chrome-devtools-mcp"]
      }
    }
  }'

# List MCP servers
curl -X POST http://localhost:3000/config/mcp/list

# Remove an MCP server
curl -X POST http://localhost:3000/config/mcp/remove \
  -H "Content-Type: application/json" \
  -d '{"name": "chrome-devtools"}'
```

### Guard Approvals

```bash theme={null}
# List approvals
curl -X POST http://localhost:3000/guard/list

# Grant approval
curl -X POST http://localhost:3000/guard/approve \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc", "scope": "session"}'

# Deny approval
curl -X POST http://localhost:3000/guard/deny \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc"}'

# Revoke a permanent approval
curl -X POST http://localhost:3000/guard/revoke \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc"}'
```

***

### Admin / Dashboard

```bash theme={null}
# Event bus statistics
curl -X POST http://localhost:3000/admin/stats

# Recent events (filters in POST body)
curl -X POST http://localhost:3000/admin/events/recent \
  -H "Content-Type: application/json" \
  -d '{"category": "agent", "limit": 50}'

# Live event stream (SSE)
curl -N -X POST http://localhost:3000/admin/events/stream

# All registered agents
curl -X POST http://localhost:3000/admin/agents

# Agents in a specific session
curl -X POST http://localhost:3000/admin/sessions/agents \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess-001"}'

# Tenant list
curl -X POST http://localhost:3000/admin/tenants
```

***

## Endpoint Conventions

Savant uses HTTP POST for all API operations. Exceptions: A2A discovery (`GET /.well-known/agent-card.json`), BFF health (`GET /health`), and a few BFF GETs for read-only endpoints.

***

## Further Reading

* [Managing Sessions](./managing-sessions) — step-by-step guide for the session lifecycle
* [Sessions](../concepts/sessions) — the session-first architecture
* [OpenAPI Specification](../api-reference/openapi.yaml) — complete endpoint listing