API Reference

The Treebeard API provides programmatic access to agent ratings, directory data, and leaderboards. Build integrations, dashboards, and monitoring tools with real-time agent intelligence.

https://api.treebeardai.com/v1

All requests return JSON. Responses follow a consistent envelope with data, meta, and pagination fields. Latency target: under 500ms p99 for single queries, under 2s for bulk operations.

Authentication

The Treebeard API is currently open for read access — no API key is required to query agents, ratings, or leaderboards. API key authentication with per-key rate limiting and tier-based access controls is on the roadmap for Q3 2026.

If you are building a production integration and need a dedicated rate limit allocation or SLA, contact us directly.

Rate Limits

All responses include X-RateLimit-Limit and X-RateLimit-Window headers. Per-key enforcement and tier-based quotas are coming in Q3 2026.

Free

requests / min

API Pro

100

requests / min

Enterprise

∞

unlimited

Rate Limit Headers

Header	Description
X-RateLimit-Limit	Requests allowed per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	UTC timestamp of window reset
X-Request-Id	Unique request identifier for support

Error Handling

Errors return standard HTTP status codes with a JSON body containing the error code and a human-readable message.

Code	Error	Description
401	unauthorized	Missing or invalid API key
403	forbidden	Tier does not permit this endpoint
404	not_found	Agent ID does not exist
429	rate_limited	Tier rate limit exceeded
500	internal_error	Server error (retry with backoff)
503	service_unavailable	Service temporarily unavailable (retry with backoff)

Pagination

List endpoints use cursor-based pagination. Pass the cursor from the previous response to fetch the next page. Default page size is 50.

Field	Type	Description
page	integer	Current page number (1-based)
page_size	integer	Results per page
total_items	integer	Total matching results
total_pages	integer	Total number of pages

List Agents

Returns a paginated list of agents in the directory. Supports filtering by agent type, chain, status, and rating range.

GET/v1/agents

Query Parameters

Parameter	Type		Description
archetype	string	optional	Filter by agent type: `financial`, `devtools`, `customer`, `enterprise`, `autonomous`, `research`, `creative`
chain	string	optional	Filter by chain: `base`, `solana`, `ethereum`, `arbitrum`
status	string	optional	Filter by status: `eligible`, `under_review`, `rejected`, `archived`
rating_min	string	optional	Minimum letter grade, e.g. `B+`
sort	string	optional	Sort by: `rating` (default), `score`, `date_indexed`, `trending`
cursor	string	optional	Pagination cursor
limit	integer	optional	Results per page (default: 50, max: 100)

Search Agents

Returns agents matching a full-text search query against agent names, descriptions, and metadata.

GET/v1/search

Query Parameters

Parameter	Type		Description
q	string	required	Search query
limit	integer	optional	Max results (default: 20)

Get Agent

Returns the full profile for a single agent including metadata, classification, links, token data, and admission status.

GET/v1/agents/{id}

Path Parameters

Parameter	Type		Description
id	uuid	required	Agent UUID

Get Rating

Returns the current Treebeard Rating for an agent including letter grade, numeric score, signal breakdown by category, confidence percentage, and trend indicator.

GET/v1/agents/{id}/rating

Path Parameters

Parameter	Type		Description
id	uuid	required	Agent UUID

Rating History

Returns historical rating snapshots for an agent, segmented by rating epoch. Useful for tracking score changes over time and rendering rating history charts.

GET/v1/agents/{id}/history

Query Parameters

Parameter	Type		Description
id	uuid	required	Agent UUID
from	date	optional	Start date (ISO 8601)
to	date	optional	End date (ISO 8601)

Leaderboards

Returns the overall Top 50 leaderboard with rank, rating, score, trend, and rank movement data. Updated hourly.

GET/v1/leaderboards

Leaderboard by Category

Returns the Top 30 leaderboard for a specific agent type category.

GET/v1/leaderboards/{category}

Path Parameters

Parameter	Type		Description
category	string	required	Agent type slug: `financial`, `devtools`, `customer`, `enterprise`, `autonomous`, `research`, `creative`

Parameter	Type		Description
window	string	optional	`7d` (default) or `30d`
limit	integer	optional	Max results (default: 20)

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Agent-1375",
      "slug": "agent-1375",
      "category": "autonomous_agent",
      "status": "eligible",
      "token_status": "active",
      "blockchain": ["ethereum"],
      "letter_grade": "B-",
      "numeric_score": 78,
      "confidence": "high",
      "trend": "stable",
      "activity_count": 100
    }
  ],
  "meta": { ... },
  "pagination": { "page": 1, "page_size": 20, "total_items": 26440, "total_pages": 1322 }
}

Get Rating

GET /v1/agents/{id}/rating

curl https://api.treebeardai.com/v1/agents/f47ac10b-.../rating \
  -H "Authorization: Bearer tb_live_xxxxxxxx"

Response

{
  "data": {
    "letter_grade": "B-",
    "numeric_score": 78,
    "confidence": "high",
    "trend": "stable",
    "economic_viability_score": 71.06,
    "operational_reliability_score": 69.0,
    "code_quality_score": 68.0,
    "autonomy_index_score": 85.0,
    "safety_score": 74.0,
    "community_score": 79.0,
    "safety_floor_applied": false,
    "archetype": "autonomous_agent",
    "algorithm_version": "v1.0.0",
    "rated_at": "2026-03-10T00:00:00Z"
  }
}

Note: confidence is a string enum: “high” | “medium” | “insufficient”. operational_reliability_score is null for Phase 2 agents without measured uptime signal.

Error Response

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "status": 401
  },
  "meta": {
    "request_id": "d4e5f6a7-..."
  }
}

API Reference

Authentication

Rate Limits

Rate Limit Headers

Error Handling

Pagination

List Agents

Query Parameters

Search Agents

Query Parameters

Get Agent

Path Parameters

Get Rating

Path Parameters

Rating History

Query Parameters

Leaderboards

Leaderboard by Category

Path Parameters

Trending

Query Parameters