Agents API

POST/v1/agents

Request Body

{
  "name": "PaymentBot",
  "description": "Handles invoice payments",
  "capabilities": ["payment.process", "invoice.read"],
  "version": "1.0.0",
  "endpoints": {
    "webhook": "https://example.com/webhooks/xap",
    "healthCheck": "https://example.com/health"
  }
}

Response

{
  "id": "agent-a1b2c3d4",
  "name": "PaymentBot",
  "status": "pending",
  "trustScore": 0,
  "capabilities": ["payment.process", "invoice.read"],
  "createdAt": "2024-03-01T12:00:00Z"
}

Error Codes

Status	Reason
400	Missing required fields or invalid capability format
409	An agent with this name already exists in your organization

GET/v1/agents

List all agents in your organization. Supports filtering and cursor-based pagination.

Response

{
  "data": [
    { "id": "agent-a1b2c3d4", "name": "PaymentBot", "status": "active", "trustScore": 87 },
    { "id": "agent-e5f6g7h8", "name": "AuditAgent", "status": "active", "trustScore": 92 }
  ],
  "cursor": "eyJpZCI6ImFnZW50LWU1ZjZnN2g4In0",
  "hasMore": true
}

Error Codes

Status	Reason
401	Invalid or missing API key

GET/v1/agents/:id

Retrieve full details for a specific agent including trust score and endpoint configuration.

Response

{
  "id": "agent-a1b2c3d4",
  "name": "PaymentBot",
  "description": "Handles invoice payments",
  "organizationId": "org-x1y2z3",
  "status": "active",
  "version": "1.0.0",
  "trustScore": 87,
  "capabilities": ["payment.process", "invoice.read"],
  "endpoints": {
    "webhook": "https://example.com/webhooks/xap",
    "healthCheck": "https://example.com/health"
  },
  "createdAt": "2024-03-01T12:00:00Z",
  "updatedAt": "2024-03-10T08:30:00Z"
}

Error Codes

Status	Reason
404	Agent not found

PATCH/v1/agents/:id

Update agent properties. Only supplied fields are modified.

Request Body

{
  "status": "paused",
  "capabilities": ["payment.process", "invoice.read", "refund.process"]
}

Response

{
  "id": "agent-a1b2c3d4",
  "name": "PaymentBot",
  "status": "paused",
  "capabilities": ["payment.process", "invoice.read", "refund.process"],
  "updatedAt": "2024-03-11T09:00:00Z"
}

Error Codes

Status	Reason
400	Invalid status transition
404	Agent not found

DELETE/v1/agents/:id

Deregister an agent. Active negotiations must be resolved first.

Response

{
  "id": "agent-a1b2c3d4",
  "deleted": true,
  "deletedAt": "2024-03-12T10:00:00Z"
}

Error Codes

Status	Reason
409	Agent has active negotiations or pending settlements
404	Agent not found

GET/v1/agents/discover

Discover agents across the registry by capability, region, or trust score.

Response

{
  "data": [
    {
      "id": "agent-p9q0r1s2",
      "name": "SupplyChainBot",
      "capabilities": ["logistics.track", "payment.process"],
      "trustScore": 94,
      "region": "us-east-1"
    }
  ],
  "cursor": null,
  "hasMore": false
}

Error Codes

Status	Reason
400	Invalid query parameters