Skip to main content

​
Overview

Every Bindu agent exposes a standard HTTP API that follows the A2A (Agent-to-Agent) protocol. This API is automatically generated when you call bindufy() — you never write route handlers manually. The API is generic and works identically across all agents, regardless of their specific capabilities. Domain-specific behavior is handled by your agent’s handler function, not by custom endpoints.

​
Base URL

http://localhost:3773

​
Architecture: One Endpoint, Many Methods

Unlike traditional REST APIs, Bindu uses JSON-RPC 2.0 over HTTP. Almost all operations go to a single endpoint: 
POST /
The method field in the request body determines what operation to perform:
MethodPurpose
message/sendSend a message to the agent, creates a new task
message/streamStream task updates (experimental)
tasks/getGet the status and results of a task
tasks/listList all tasks for the current context
tasks/cancelCancel a running task
tasks/feedbackProvide feedback on a completed task
tasks/pushNotificationConfig/setRegister a webhook for task updates
tasks/pushNotificationConfig/getRead the webhook registered for a task
tasks/pushNotificationConfig/listList webhook configs for a task
tasks/pushNotificationConfig/deleteRemove a webhook from a task
contexts/listList all conversation contexts
contexts/clearClear a conversation context

​
Quick Start

​
1. Send a Message

curl -X POST http://localhost:3773 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello!"}],
        "messageId": "msg-001",
        "contextId": "ctx-001",
        "taskId": "task-001",
        "kind": "message"
      }
    },
    "id": "1"
  }'

​
2. Get Task Status

curl -X POST http://localhost:3773 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/get",
    "params": {
      "taskId": "task-001"
    },
    "id": "2"
  }'

​
3. Get Agent Card

curl http://localhost:3773/.well-known/agent.json

​
Authentication

Bindu supports three layers of authentication:

​
Layer 1: Bearer Token (Required)

OAuth2 access token from Ory Hydra: 
Authorization: Bearer <access-token>
Scopes:
  • agent:read — Read operations (tasks/get, tasks/list)
  • agent:write — Write operations (message/send, tasks/cancel)
  • agent:execute — Both read and write (legacy)

​
Layer 2: DID Signature (Optional, Agent-to-Agent)

For agent-to-agent communication, sign requests with your DID: 
X-DID: did:bindu:author:agent:id
X-DID-Timestamp: 1713564000
X-DID-Signature: <base58-encoded-signature>

​
Layer 3: x402 Payment (Optional, Paid Agents)

For paid agents, include payment proof: 
X-PAYMENT: <base64-encoded-x402-payload>

​
Task States

Every interaction creates a Task with a unique ID. Tasks follow this state machine:

​
Non-Terminal States

submitted

Queued, not yet picked up by worker

working

Agent is actively processing

input-required

Paused, waiting for user clarification

auth-required

Paused, waiting for authentication

​
Terminal States

completed

Success, artifacts available

failed

Processing error occurred

canceled

User terminated the task

rejected

Agent declined to process
Terminal tasks are immutable. To refine a completed answer, submit a new message/send with referenceTaskIds pointing to the old task.

​
Error Codes

Errors follow JSON-RPC 2.0 format: 
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "field": "taskId", "reason": "required" }
  }
}

​
Standard JSON-RPC Errors

CodeNameMeaning
-32700Parse errorInvalid JSON
-32600Invalid RequestMalformed JSON-RPC
-32601Method not foundUnknown method
-32602Invalid paramsSchema validation failed
-32603Internal errorServer bug

​
A2A Protocol Errors

CodeNameMeaning
-32001TaskNotFoundTask doesn’t exist
-32002TaskNotCancelableTask already terminal
-32003PushNotificationNotSupportedAgent doesn’t support push
-32004UnsupportedOperationOperation not available
-32005ContentTypeNotSupportedUnsupported output format

​
Bindu Extensions

CodeNameMeaning
-32009AuthenticationRequiredMissing bearer token
-32010InvalidTokenToken introspection failed
-32011TokenExpiredToken past expiration
-32012InvalidTokenSignatureDID signature verification failed
-32013InsufficientPermissionsMissing required scope

​
Discovery Endpoints

​
Agent Card

GET /.well-known/agent.json
Returns the A2A discovery document with:
  • Agent DID
  • Capabilities
  • Published skills
  • Payment requirements
  • Supported protocols

​
Skills List

GET /agent/skills
Returns array of all skills the agent publishes.

​
Skill Details

GET /agent/skills/{skillId}
Returns detailed documentation for a specific skill.

​
Health & Monitoring

​
Health Check

GET /health
Returns 200 when healthy, 503 when degraded. Includes per-component status.

​
Metrics

GET /metrics
Prometheus text format metrics including:
  • Request counts and latency
  • Active tasks by state
  • Token usage
  • Error rates

​
Webhooks & Push Notifications

For long-running tasks, you don’t have to poll. Pass a push_notification_config inside configuration and the agent will POST updates to your webhook as the task progresses: 
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": { "...": "..." },
    "configuration": {
      "acceptedOutputModes": ["application/json"],
      "long_running": true,
      "push_notification_config": {
        "id": "<uuid>",
        "url": "https://your-app.com/webhook",
        "token": "secret_abc123"
      }
    }
  },
  "id": "1"
}
Your webhook receives status updates (state changes) and artifact updates as they happen. See the Push Notifications guide for the full event shapes and how to build a receiver.

​
Best Practices

Generate a UUID for each message and reuse it if you need to retry. Check tasks/list before resending to avoid duplicates.
Start with 1s intervals, double up to 30s max. Don’t hammer the server with rapid polls.
Use the same contextId across multiple messages to maintain conversation history.
Don’t assume tasks always complete successfully. Check for failed, canceled, and rejected states.
For agent-to-agent calls, always verify the response signature against the agent’s public key.

​
Next Steps

Authentication Guide

OAuth2 and DID setup

Payment Integration

x402 payment protocol

Push Notifications

Webhook updates for long-running tasks

Example Agents

Working code examples