Skip to content

HTTP API

Lango exposes an HTTP API for health monitoring, agent discovery, authentication, and chat interaction.

Server Configuration

Settings: lango settings → Server

{
  "server": {
    "host": "localhost",
    "port": 18789,
    "httpEnabled": true
  }
}
Key Type Default Description
server.host string localhost Bind address for the HTTP server
server.port int 18789 Port number
server.httpEnabled bool true Enable the HTTP server

Endpoints

Health Check

GET /health

Returns the server health status. Use this for monitoring, load balancer probes, and Docker health checks.

curl http://localhost:18789/health

Agent Card (A2A)

GET /.well-known/agent.json

Returns the agent's A2A agent card when the A2A protocol is enabled (a2a.enabled: true). This endpoint follows the Agent-to-Agent protocol specification for remote agent discovery.

Authentication

Authentication endpoints are available when OIDC is configured. See Authentication for details on the OAuth login flow and token management.

Chat

The main chat endpoint accepts user messages and returns agent responses. When WebSocket is enabled, responses are streamed in real time via WebSocket events alongside the standard HTTP response.

P2P Network

When P2P networking is enabled (p2p.enabled: true), the gateway exposes read-only endpoints for querying the running node's state. When OIDC authentication is configured, these endpoints require authentication. Without OIDC, they are accessible without authentication (development mode).

GET /api/p2p/status

Returns the local node's peer ID, listen addresses, and connected peer count.

curl http://localhost:18789/api/p2p/status

{
  "peerId": "12D3KooW...",
  "listenAddrs": ["/ip4/0.0.0.0/tcp/9000"],
  "connectedPeers": 2,
  "mdnsEnabled": true
}

GET /api/p2p/peers

Returns the list of currently connected peers with their IDs and multiaddresses.

curl http://localhost:18789/api/p2p/peers

{
  "peers": [
    {
      "peerId": "12D3KooW...",
      "addrs": ["/ip4/172.20.0.3/tcp/9002"]
    }
  ],
  "count": 1
}

GET /api/p2p/identity

Returns the active local DID, when available, together with the libp2p peer ID. The DID may be v1 or v2 depending on the configured identity provider.

curl http://localhost:18789/api/p2p/identity

{
  "did": "did:lango:v2:4f2c9a8b7d6e5c1a0f1e2d3c4b5a697887766554",
  "peerId": "12D3KooW..."
}

If no identity provider is configured, did is null.

GET /api/p2p/reputation

Returns the trust score and exchange history for a peer. The peer_did query parameter is required.

curl "http://localhost:18789/api/p2p/reputation?peer_did=did:lango:02abc..."

{
  "peerDid": "did:lango:02abc...",
  "trustScore": 0.85,
  "successfulExchanges": 42,
  "failedExchanges": 3,
  "timeoutCount": 1,
  "firstSeen": "2026-02-20T10:00:00Z",
  "lastInteraction": "2026-02-24T14:30:00Z"
}

If the reputation system is not enabled or the peer has no history, the response indicates the default state (new peers are trusted by default).

GET /api/p2p/pricing

Returns tool pricing configuration. Use the optional tool query parameter to query a specific tool's price.

# Get all tool pricing
curl http://localhost:18789/api/p2p/pricing

{
  "enabled": true,
  "currency": "USDC",
  "perQuery": "0.10",
  "toolPrices": {
    "knowledge_search": "0.25",
    "browser_navigate": "0.50"
  }
}

# Get pricing for a specific tool
curl "http://localhost:18789/api/p2p/pricing?tool=knowledge_search"

{
  "tool": "knowledge_search",
  "price": "0.25",
  "currency": "USDC"
}

Note

These REST endpoints query the running server's persistent P2P node. The CLI commands (lango p2p status, etc.) create ephemeral nodes for one-off operations. For monitoring and automation, prefer the REST API.