API Reference

Complete reference for all Bindu API endpoints. All endpoints use JSON-RPC 2.0 protocol over HTTP POST requests.

Base URL

http://localhost:8030/

All API requests require the Content-Type: application/json header. Authentication endpoints require a Bearer token in the Authorization header.

Authentication

Bindu uses Bearer token authentication for protected endpoints.

Authorization: Bearer <your-token>

Message Operations

Send Message

Send a message to an agent and wait for a complete response.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "provide sunset quote"
          }
        ],
        "kind": "message",
        "messageId": "550e8400-e29b-41d4-a716-446655440027",
        "contextId": "550e8400-e29b-41d4-a716-446655440027",
        "taskId": "550e8400-e29b-41d4-a716-446655440041"
      },
      "configuration": {
        "acceptedOutputModes": ["application/json"]
      }
    },
    "id": "550e8400-e29b-41d4-a716-446655440024"
  }'

Request Parameters:

Parameter	Type	Required	Description
`message`	Message	Yes	The message object containing the user’s request
`message.role`	string	Yes	Role of the sender: `user`, `agent`, or `system`
`message.parts`	Part[]	Yes	Array of message parts (text, file, or data)
`message.kind`	string	Yes	Always `"message"`
`message.messageId`	UUID	Yes	Unique identifier for the message
`message.contextId`	UUID	Yes	Context identifier for the conversation
`message.taskId`	UUID	Yes	Task identifier
`message.referenceTaskIds`	UUID[]	No	Array of related task IDs
`configuration`	object	Yes	Message configuration
`configuration.acceptedOutputModes`	string[]	Yes	Accepted MIME types for output

Response:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440024",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440041",
    "contextId": "550e8400-e29b-41d4-a716-446655440027",
    "kind": "task",
    "status": {
      "state": "completed",
      "timestamp": "2025-10-13T17:30:00Z"
    },
    "artifacts": [
      {
        "artifactId": "...",
        "parts": [
          {
            "kind": "text",
            "text": "The sunset is a daily reminder..."
          }
        ]
      }
    ],
    "history": [...]
  }
}

Send Message with Reference

Send a follow-up message that references a previous task.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "make it shorter"
          }
        ],
        "kind": "message",
        "messageId": "550e8400-e29b-41d4-a716-446655440027",
        "contextId": "550e8400-e29b-41d4-a716-446655440027",
        "taskId": "550e8400-e29b-41d4-a716-446655440042",
        "referenceTaskIds": ["550e8400-e29b-41d4-a716-446655440041"]
      },
      "configuration": {
        "acceptedOutputModes": ["application/json"]
      }
    },
    "id": "550e8400-e29b-41d4-a716-446655440024"
  }'

Use referenceTaskIds to maintain conversation context and reference previous outputs.

Task Operations

Get Task

Retrieve the current status and details of a specific task.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/get",
    "params": {
      "taskId": "550e8400-e29b-41d4-a716-446655440041"
    },
    "id": "550e8400-e29b-41d4-a716-446655440025"
  }'

Request Parameters:

Parameter	Type	Required	Description
`taskId`	UUID	Yes	The unique identifier of the task
`historyLength`	number	No	Number of history items to include

Response:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440025",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440041",
    "contextId": "550e8400-e29b-41d4-a716-446655440027",
    "kind": "task",
    "status": {
      "state": "completed",
      "timestamp": "2025-10-13T17:30:00Z"
    },
    "artifacts": [...],
    "history": [...],
    "metadata": {}
  }
}

List Tasks

List all tasks in the current session.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/list",
    "params": {},
    "id": "550e8400-e29b-41d4-a716-446655440099"
  }'

Request Parameters:

Parameter	Type	Required	Description
`historyLength`	number	No	Number of history items to include per task
`metadata`	object	No	Additional metadata for filtering

Response:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440099",
  "result": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440041",
      "contextId": "550e8400-e29b-41d4-a716-446655440027",
      "kind": "task",
      "status": {...},
      "artifacts": [...],
      "history": [...]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440042",
      "contextId": "550e8400-e29b-41d4-a716-446655440027",
      "kind": "task",
      "status": {...},
      "artifacts": [...],
      "history": [...]
    }
  ]
}

Cancel Task

Cancel a running task.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/cancel",
    "params": {
      "taskId": "550e8400-e29b-41d4-a716-446655440041"
    },
    "id": "550e8400-e29b-41d4-a716-446655440025"
  }'

Tasks can only be canceled while in pending or working state. Completed or failed tasks cannot be canceled.

Submit Feedback

Provide feedback on a completed task.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/feedback",
    "params": {
      "taskId": "550e8400-e29b-41d4-a716-446655440045",
      "feedback": "Great job! The response was very helpful and accurate.",
      "rating": 5,
      "metadata": {
        "category": "quality",
        "source": "user",
        "helpful": true
      }
    },
    "id": "550e8400-e29b-41d4-a716-446655440024"
  }'

Request Parameters:

Parameter	Type	Required	Description
`taskId`	UUID	Yes	The unique identifier of the task
`feedback`	string	Yes	Feedback text
`rating`	number	No	Rating from 1 (lowest) to 5 (highest)
`metadata`	object	No	Additional feedback metadata

Context Operations

List Contexts

List all conversation contexts.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "contexts/list",
    "params": {
      "length": 10
    },
    "id": "550e8400-e29b-41d4-a716-446655440025"
  }'

Request Parameters:

Parameter	Type	Required	Description
`length`	number	No	Maximum number of contexts to return
`historyLength`	number	No	Number of history items to include
`metadata`	object	No	Additional metadata for filtering

Response:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440025",
  "result": [
    {
      "contextId": "550e8400-e29b-41d4-a716-446655440027",
      "kind": "context",
      "tasks": [
        "550e8400-e29b-41d4-a716-446655440041",
        "550e8400-e29b-41d4-a716-446655440042"
      ],
      "name": "Sunset Quotes Conversation",
      "role": "user",
      "createdAt": "2025-10-13T17:00:00Z",
      "updatedAt": "2025-10-13T17:30:00Z",
      "status": "active"
    }
  ]
}

Clear Context

Clear a context and all its associated tasks.

curl -X POST http://localhost:8030/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "contexts/clear",
    "params": {
      "contextId": "550e8400-e29b-41d4-a716-446655440037"
    },
    "id": "550e8400-e29b-41d4-a716-446655440025"
  }'

Request Parameters:

Parameter	Type	Required	Description
`contextId`	UUID	Yes	The unique identifier of the context to clear

Clearing a context will remove all associated tasks and their history. This action cannot be undone.

Agent Information

Get Agent Card

Retrieve the agent’s card containing capabilities, skills, and metadata.

curl -X GET http://localhost:8030/.well-known/agent.json

Response:

{
  "id": "e091ddb0-b2c8-4bd8-991f-dfd1ecbb9da6",
  "name": "First Agent",
  "description": "A helpful AI agent",
  "url": "http://localhost:8030",
  "version": "1.0.0",
  "protocolVersion": "0.3.0",
  "documentationUrl": "https://docs.saptha.me",
  "agentTrust": {
    "identityProvider": "keycloak",
    "inheritedRoles": [...],
    "trustVerificationRequired": false
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "skills": [
    {
      "id": "text-generation",
      "name": "Text Generation",
      "description": "Generate human-like text responses",
      "tags": ["nlp", "generation"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain", "application/json"]
    }
  ],
  "kind": "agent",
  "numHistorySessions": 10
}

Resolve DID

Resolve a Decentralized Identifier (DID) to get agent information.

curl -X POST http://localhost:8030/did/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:bindu:raahul_at_saptha_me:first_agent:e091ddb0b2c84bd8991fdfd1ecbb9da6"
  }'

Request Parameters:

Parameter	Type	Required	Description
`did`	string	Yes	The Decentralized Identifier to resolve

Response:

{
  "didDocument": {
    "id": "did:bindu:raahul_at_saptha_me:first_agent:e091ddb0b2c84bd8991fdfd1ecbb9da6",
    "verificationMethod": [
      {
        "id": "...",
        "type": "Ed25519VerificationKey2020",
        "controller": "...",
        "publicKeyMultibase": "..."
      }
    ],
    "service": [
      {
        "id": "...",
        "type": "AgentService",
        "serviceEndpoint": "http://localhost:8030"
      }
    ]
  }
}

Error Responses

All errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440024",
  "error": {
    "code": -32001,
    "message": "The specified task ID was not found...",
    "data": {
      "taskId": "550e8400-e29b-41d4-a716-446655440041"
    }
  }
}

Common Error Codes

Code	Error	Description
-32700	Parse Error	Invalid JSON
-32600	Invalid Request	Request validation failed
-32601	Method Not Found	Method doesn’t exist
-32602	Invalid Params	Invalid parameters
-32603	Internal Error	Server error
-32001	Task Not Found	Task ID not found
-32002	Task Not Cancelable	Cannot cancel task
-32009	Authentication Required	Missing or invalid token
-32010	Invalid Token	Token is malformed
-32011	Token Expired	Token has expired
-32013	Insufficient Permissions	Insufficient permissions

Rate Limiting

Rate limiting policies depend on your deployment configuration. Check with your agent administrator for specific limits.

Webhooks & Push Notifications

Push notifications support depends on agent configuration. Check the agent card’s capabilities.pushNotifications field.

SDK Examples

Python SDK

import requests
import uuid
from typing import Dict, Any

class BinduClient:
    def __init__(self, base_url: str, token: str = None):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json"
        }
        if token:
            self.headers["Authorization"] = f"Bearer {token}"
    
    def send_message(self, text: str, context_id: str = None, task_id: str = None) -> Dict[str, Any]:
        context_id = context_id or str(uuid.uuid4())
        task_id = task_id or str(uuid.uuid4())
        
        payload = {
            "jsonrpc": "2.0",
            "method": "message/send",
            "params": {
                "message": {
                    "role": "user",
                    "parts": [{"kind": "text", "text": text}],
                    "kind": "message",
                    "messageId": str(uuid.uuid4()),
                    "contextId": context_id,
                    "taskId": task_id
                },
                "configuration": {
                    "acceptedOutputModes": ["application/json"]
                }
            },
            "id": str(uuid.uuid4())
        }
        
        response = requests.post(self.base_url, json=payload, headers=self.headers)
        return response.json()
    
    def get_task(self, task_id: str) -> Dict[str, Any]:
        payload = {
            "jsonrpc": "2.0",
            "method": "tasks/get",
            "params": {"taskId": task_id},
            "id": str(uuid.uuid4())
        }
        
        response = requests.post(self.base_url, json=payload, headers=self.headers)
        return response.json()

# Usage
client = BinduClient("http://localhost:8030", token="your-token")
result = client.send_message("Hello, agent!")
print(result)

JavaScript SDK

class BinduClient {
  constructor(baseUrl, token = null) {
    this.baseUrl = baseUrl;
    this.headers = {
      'Content-Type': 'application/json'
    };
    if (token) {
      this.headers['Authorization'] = `Bearer ${token}`;
    }
  }

  async sendMessage(text, contextId = null, taskId = null) {
    contextId = contextId || crypto.randomUUID();
    taskId = taskId || crypto.randomUUID();

    const payload = {
      jsonrpc: '2.0',
      method: 'message/send',
      params: {
        message: {
          role: 'user',
          parts: [{ kind: 'text', text }],
          kind: 'message',
          messageId: crypto.randomUUID(),
          contextId,
          taskId
        },
        configuration: {
          acceptedOutputModes: ['application/json']
        }
      },
      id: crypto.randomUUID()
    };

    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(payload)
    });

    return await response.json();
  }

  async getTask(taskId) {
    const payload = {
      jsonrpc: '2.0',
      method: 'tasks/get',
      params: { taskId },
      id: crypto.randomUUID()
    };

    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(payload)
    });

    return await response.json();
  }
}

// Usage
const client = new BinduClient('http://localhost:8030', 'your-token');
const result = await client.sendMessage('Hello, agent!');
console.log(result);

Next Steps

Protocol Reference

Learn about the Bindu protocol

Quickstart

Build your first agent

Protocol Types

Complete type definitions

GitHub

View source code

​API Reference

​Base URL

​Authentication

​Message Operations

​Send Message

​Send Message with Reference

​Task Operations

​Get Task

​List Tasks

​Cancel Task

​Submit Feedback

​Context Operations

​List Contexts

​Clear Context

​Agent Information

​Get Agent Card

​Resolve DID

​Error Responses

​Common Error Codes

​Rate Limiting

​Webhooks & Push Notifications

​SDK Examples

​Python SDK

​JavaScript SDK

​Next Steps

Protocol Reference

Quickstart

Protocol Types

GitHub

API Reference

Base URL

Authentication

Message Operations

Send Message

Send Message with Reference

Task Operations

Get Task

List Tasks

Cancel Task

Submit Feedback

Context Operations

List Contexts

Clear Context

Agent Information

Get Agent Card

Resolve DID

Error Responses

Common Error Codes

Rate Limiting

Webhooks & Push Notifications

SDK Examples

Python SDK

JavaScript SDK

Next Steps