Developer Documentation

Add your agents to
Bolz.Proxy

Register your organization, add AI agents to the global catalog, get verified, and let users discover and chat with your agents through an encrypted proxy.

1. Register Org2. Get API Key3. Add Agents4. Get Verified5. Protocols

Step 1

Register Your Organization

Every agent on Bolz.Proxy belongs to an organization. Start by registering yours. This is a public API — no authentication required.

curl -X POST https://proxy.bolz.dev/api/v1/orgs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme",
    "description": "Enterprise AI solutions",
    "website": "https://acme.com",
    "contact_email": "ai-team@acme.com",
    "country": "US"
  }'

Response (201 Created)

{
  "id": "a1b2c3d4-...",
  "name": "Acme Corporation",
  "slug": "acme",
  "verification_level": "basic",
  "contact_email": "ai-team@acme.com",
  "created_at": "2026-03-21T12:00:00Z"
}

Slug is permanent

The slug becomes part of every agent URI (bolz://acme/agent-name) and cannot be changed later. Choose carefully.

Step 2

Get Your API Key

To create agents and manage your organization, you need an API key. First, create one — then exchange it for a JWT token for all subsequent requests.

2a. Create an API key

Requires a JWT token (bootstrapped by admin for your first key).

curl -X POST https://proxy.bolz.dev/api/v1/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production Key",
    "scopes": ["read", "write"]
  }'

Response — save the api_key, it is only shown once

{
  "id": "...",
  "key_prefix": "bpk_9f3k8mX2",
  "label": "Production Key",
  "scopes": ["read", "write"],
  "api_key": "bpk_9f3k8mX2a7..."
}

2b. Exchange API key for JWT

curl -X POST https://proxy.bolz.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "bpk_9f3k8mX2a7..."
  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 604800
}

Use this token in all subsequent requests as Authorization: Bearer <access_token>

Step 3

Register Your Agents

Now register AI agents under your organization. Each agent gets a unique Bolz URI: bolz://your-org/agent-slug

curl -X POST https://proxy.bolz.dev/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "slug": "support",
    "description": "Handle customer inquiries, check order status, process returns.",
    "category": "ecommerce",
    "supported_locales": ["en", "es", "fr"],
    "welcome_message": "Hello! How can I help you today?",
    "target_endpoint": "https://api.acme.com/agent/v1",
    "target_protocol": "a2a",
    "target_auth_config": {
      "type": "bearer",
      "token": "your-agent-api-key"
    }
  }'

Response (201 Created)

{
  "id": "...",
  "bolz_uri": "bolz://acme/support",
  "name": "Customer Support Bot",
  "status": "active",
  "trust_score": 0,
  "total_conversations": 0,
  "created_at": "2026-03-21T12:00:00Z"
}

Agent fields reference

FieldTypeRequiredDescription
namestringYesDisplay name (2–100 chars)
slugstringYesURL-safe identifier (a-z, 0-9, hyphens)
descriptionstringNoWhat the agent does (up to 2000 chars)
categorystringNoairlines, government, banking, telecom, healthcare, ecommerce, education, real-estate
supported_localesstring[]NoLanguage codes, e.g. ["en", "ar", "ru"]. Defaults to ["en"]
welcome_messagestringNoGreeting shown before first message
target_endpointstringYesYour agent's API URL that Bolz.Proxy will forward messages to
target_protocolstringNo"a2a" (default), "rest", or "websocket"
target_auth_configobjectNoAuth for your endpoint: {"type": "bearer", "token": "..."}
agent_cardobjectNoFull A2A Agent Card JSON (merged with Bolz extensions)

Target protocol

a2a — Bolz sends JSON-RPC 2.0 tasks/send requests (Google A2A standard).
rest — Bolz sends { message, session_id } JSON POST. Your endpoint should return { response } or { message }.

Step 4

Get Verified

Verified organizations appear with a blue badge and rank higher in search results. Enterprise verification adds a gold badge and priority placement.

Basic

Email registration only. Default for new orgs.

Verified

DNS TXT record proves domain ownership.

Enterprise

Full KYB review + documents. Contact admin.

DNS verification (self-service)

Add a DNS TXT record to your domain to prove ownership:

# 1. Get verification instructions
curl "https://proxy.bolz.dev/api/v1/orgs/YOUR_ORG_ID/verify/instructions?domain=acme.com"

# Response:
# {
#   "record_type": "TXT",
#   "record_value": "bolz-verify=a1b2c3d4-...",
#   "instructions": [...]
# }

# 2. Add the TXT record to your domain DNS

# 3. Trigger verification
curl -X POST https://proxy.bolz.dev/api/v1/orgs/YOUR_ORG_ID/verify \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com" }'

# Response: { "verified": true }

Step 5

Protocol Integration

Once your agent is registered, users can interact with it through multiple protocols. Bolz.Proxy acts as a bridge — translating between MCP, A2A, and REST automatically.

MCP (Claude, ChatGPT)

Your agent is automatically available as an MCP tool. Users configure Bolz.Proxy as an MCP server:

# claude_desktop_config.json
{
  "mcpServers": {
    "bolz-proxy": {
      "command": "python",
      "args": ["-m", "src.mcp.server"]
    }
  }
}

# Then in Claude:
# "Search for customer support agents" → search_agents tool
# "Send a message to bolz://acme/support" → send_message tool

A2A (Agent-to-Agent)

Standard A2A protocol endpoints are auto-generated for every agent:

# Get Agent Card
curl https://proxy.bolz.dev/a2a/acme/support/.well-known/agent.json

# Send message (JSON-RPC 2.0)
curl -X POST https://proxy.bolz.dev/a2a/acme/support \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tasks/send",
    "params": {
      "id": "task-123",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Check my order status"}]
      }
    }
  }'

REST API (Direct)

Send messages through the Bolz.Proxy REST API:

curl -X POST https://proxy.bolz.dev/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "bolz_uri": "bolz://acme/support",
    "message": "What is my order status?",
    "session_id": null
  }'

# Response:
# {
#   "session_id": "bsess_abc123...",
#   "response": "I can help with that! Please provide your order number.",
#   "agent_name": "Customer Support Bot",
#   "latency_ms": 342
# }

WebSocket (Streaming)

// Connect
const ws = new WebSocket("wss://proxy.bolz.dev/api/v1/chat/ws");

// Send message
ws.send(JSON.stringify({
  bolz_uri: "bolz://acme/support",
  message: "Hello!",
  session_id: null
}));

// Receive response
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.response);
  // Keep session_id for follow-up messages
  // data.session_id → "bsess_abc123..."
};

Reference

API Endpoints

Base URL: https://proxy.bolz.dev

Organizations

Agents

Discovery

Chat

Auth & Keys

Verification

A2A Protocol

Need help?

For Enterprise verification, custom integrations, or partnership inquiries — reach out to the Bolz.Proxy team.

Contact usBrowse directory