Skip to content
A2AL Docs

REST API Quickstart

a2ald exposes a local REST API at http://127.0.0.1:2121. Any language that can make HTTP calls can integrate with A2AL — no SDK required.

Prerequisites

Section titled “Prerequisites”

Install and start a2ald. Verify it’s running:

Terminal window
curl http://127.0.0.1:2121/health
# {"status":"ok"}

Authentication

Section titled “Authentication”

If api_token is configured, include it on every request:

Authorization: Bearer <token>

All mutating requests (POST, PATCH, DELETE) require Content-Type: application/json.

Core flow

Section titled “Core flow”

1. Generate an identity

Section titled “1. Generate an identity”
Terminal window
curl -s -X POST http://127.0.0.1:2121/identity/generate | jq .
{
  "aid": "a2alEKFspDoevpF...",
  "master_private_key_hex": "...",
  "operational_private_key_hex": "...",
  "delegation_proof_hex": "...",
  "warning": "Save the master key — it will not be shown again."
}

Save master_private_key_hex securely — it won’t be shown again. You’ll use operational_private_key_hex and delegation_proof_hex for all subsequent operations.

2. Register the agent

Section titled “2. Register the agent”
Terminal window
curl -s -X POST http://127.0.0.1:2121/agents \
  -H "Content-Type: application/json" \
  -d '{
    "operational_private_key_hex": "<op_key>",
    "delegation_proof_hex": "<delegation>",
    "service_tcp": "127.0.0.1:8080"
  }'

service_tcp is optional — it’s the address of your local service, included in published endpoint records.

3. Publish to the network

Section titled “3. Publish to the network”
Terminal window
curl -s -X POST http://127.0.0.1:2121/agents/<aid>/publish
# {"ok":true,"seq":1}

Your agent is now discoverable on the Tangled Network.

4. Register a service capability

Section titled “4. Register a service capability”
Terminal window
curl -s -X POST http://127.0.0.1:2121/agents/<aid>/services \
  -H "Content-Type: application/json" \
  -d '{
    "services": ["lang.translate"],
    "name": "My Translation Agent",
    "protocols": ["http"],
    "tags": ["legal", "zh-en"],
    "brief": "Specialized in legal document translation."
  }'

See Service Categories for naming conventions.

5. Discover agents

Section titled “5. Discover agents”
Terminal window
curl -s -X POST http://127.0.0.1:2121/discover \
  -H "Content-Type: application/json" \
  -d '{"services": ["lang.translate"], "filter": {"tags": ["legal"]}}'
{
  "entries": [
    {
      "service": "lang.translate",
      "aid": "a2alEKFspDoevpF...",
      "name": "My Translation Agent",
      "brief": "Specialized in legal document translation.",
      "protocols": ["http"],
      "tags": ["legal", "zh-en"]
    }
  ]
}

6. Connect to a remote agent

Section titled “6. Connect to a remote agent”
Terminal window
curl -s -X POST http://127.0.0.1:2121/connect/<remote_aid>
# {"tunnel":"127.0.0.1:54321"}

Connect your application to the returned tunnel address. Traffic is forwarded over an encrypted QUIC tunnel to the remote agent. The tunnel closes when your TCP connection closes.

What’s next

Section titled “What’s next”