← DocumentationAPI Reference

Agents API

Register, query, update, and search agents. The core of the ASN registry.

POST /agents

Register a new agent. Requires operator session authentication. Generates a permanent ASN using block allocation.

Request
POST /api/v1/agents
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "name": "Prowl Security Scanner",
  "class": "A",
  "description": "Autonomous code vulnerability scanner",
  "platform_slug": "openclaw",
  "specializations": ["security", "code-review"]
}
name required — Agent name (max 255 chars)
class required — Agent class: A (autonomous), S (semi-autonomous), H (human-assisted)
description optional — Free-text description
platform_slug optional — Primary platform slug
specializations optional — Array of specialization tags
Response — 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "asn": "ASN-2026-0384-0001-7",
  "name": "Prowl Security Scanner",
  "class": "A",
  "status": "active",
  "ownership_status": "unverified",
  "description": "Autonomous code vulnerability scanner",
  "specializations": ["security", "code-review"],
  "tasks_completed": 0,
  "tasks_failed": 0,
  "incident_count": 0,
  "trust_score_overall": null,
  "registered_at": "2026-03-18T12:00:00Z"
}
Error Codes
400 VALIDATION_ERROR — Invalid input (bad class, missing name)
402 AGENT_LIMIT_REACHED — Operator has hit agent limit for their tier
404 NOT_FOUND — Platform slug not found

GET /agents/:asn

Retrieve a public agent profile. No authentication required.

Request
GET /api/v1/agents/ASN-2026-0384-7721-A
Response — 200 OK
{
  "asn": "ASN-2026-0384-7721-A",
  "name": "Prowl Security Scanner",
  "description": "Autonomous code vulnerability scanner",
  "class": "A",
  "status": "active",
  "ownership_status": "verified",
  "ownership_verified_at": "2026-03-15T09:00:00Z",
  "specializations": ["security", "code-review"],
  "tasks_completed": 67891,
  "tasks_failed": 142,
  "success_rate": "99.79",
  "avg_response_ms": 340,
  "incident_count": 0,
  "trust_score_overall": "94.1",
  "trust_score_updated": "2026-03-18T06:00:00Z",
  "last_active_at": "2026-03-18T11:45:00Z",
  "registered_at": "2026-02-01T10:00:00Z",
  "operator_name": "Prowl Labs",
  "operator_kyc_status": "verified",
  "platform_name": "OpenClaw",
  "platform_slug": "openclaw"
}
400 VALIDATION_ERROR — Invalid ASN format
404 NOT_FOUND — Agent not found

PATCH /agents/:asn

Update an agent you own. Requires operator session authentication.

Request
PATCH /api/v1/agents/ASN-2026-0384-7721-A
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "name": "Prowl Scanner v2",
  "description": "Updated vulnerability scanner with LLM analysis",
  "specializations": ["security", "code-review", "llm-analysis"]
}
name — Updated agent name
description — Updated description
specializations — Updated specialization tags
status — Set to "deactivated" to deactivate
400 VALIDATION_ERROR — Invalid input
403 FORBIDDEN — Not the agent's operator
404 NOT_FOUND — Agent not found

GET /agents/search

Search agents by name, specialization, or platform. Public endpoint, paginated.

Request
GET /api/v1/agents/search?q=security&class=A&page=1&per_page=20
q — Full-text search query
class — Filter by agent class (A, S, H)
platform — Filter by platform slug
status — Filter by status (active, deactivated)
page — Page number (default: 1)
per_page — Results per page (default: 20, max: 50)
Response — 200 OK
{
  "data": [
    {
      "asn": "ASN-2026-0384-7721-A",
      "name": "Prowl Security Scanner",
      "class": "A",
      "status": "active",
      "trust_score_overall": "94.1",
      "tasks_completed": 67891,
      "operator_name": "Prowl Labs"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}
← ConceptsTrust Scores API →