Endpoints
Official endpoints for the H.I.V.E. Protocol
Core Endpoints
These are the three essential endpoints for a minimal agent.
1. POST /tasks
This is the primary endpoint for receiving and processing tasks from other agents.
- Method:
POST - Request Body: A standard message with
type: "task_request".
{
"from": "hive:agentid:requester123",
"to": "hive:agentid:translator456",
"type": "task_request",
"data": {
"task_id": "task-123",
// capability specific task payload
},
"sig": "ed25519_signature_here"
}- Success Response: A message with
type: "task_result"and HTTP status200 OK.
{
"from": "hive:agentid:translator456",
"to": "hive:agentid:requester123",
"type": "task_result",
"data": {
"task_id": "task-123",
// task specific response
},
"sig": "ed25519_signature_here"
}- Error Response: A message with
type: "task_error"and an appropriate HTTP status code (e.g.,400,401,500).
{
"from": "hive:agentid:translator456",
"to": "hive:agentid:requester123",
"type": "task_error",
"data": {
"task_id": "task-123",
"code": 400 /* H.I.V.E supported error formats */,
"error": "...",
// task specific error response
},
"sig": "ed25519_signature_here"
}2. GET /capabilities
This endpoint allows other agents to discover the capabilities of this agent.
- Method:
GET - Response Body: A JSON object containing a list of the agent's capabilities.
{
"from": "hive:agentid:translator456",
"to": "hive:agentid:requester123",
"type": "capability_response",
"data": {
"capabilities": [
{
"id": "text-translation",
"input": { "text": "string", "target_lang": "string" },
"output": { "translated_text": "string" }
}
],
"endpoint": "https://translator456.example.com/api"
},
"sig": "ed25519_signature_here"
}3. GET /status
A health check endpoint.
- Method:
GET - Response Body: A JSON object indicating the agent's status.
{
"from": "hive:agentid:translator456",
"to": "hive:agenti:requester123",
"type": "heartbeat",
"data": {
"status": "online",
"uptime": 86400,
"endpoint": "https://translator456.example.com/api"
},
"sig": "ed25519_signature_here"
}Optional Endpoints (Tier 2+)
As agents implement higher tiers, they may add more specialized endpoints.
GET /tasks/{taskId}
Allows querying the status of a specific task.
- Method:
GET - URL Parameter:
taskId- The unique ID of the task. - Response Body: A JSON object with the current state of the task.
GET /identity
Provides the agent's public identity information, including its public key. This can be used as a fallback for public key distribution if a registry is not used.
- Method:
GET - Response Body:
{
"from": "hive:agentid:translator456",
"to": "hive:agenti:requester123",
"type": "agent_identity",
"data": {
"agent_id": "hive:agentid:translator456",
"public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
"endpoint": "https://translator456.example.com/api"
},
"sig": "ed25519_signature_here"
}Simplicity: By standardizing on a small number of RESTful endpoints, the protocol remains easy to implement and debug using common web development tools.