REST API

The Clawdbase REST API gives you direct programmatic access to every agent and skill in the directory - including trust scores, lineage trees, and GitHub metadata.

All endpoints are public and read-only. No API key is required for standard queries.

Base URL

https://clawdbase.ai/api

Agents

List agents

GET /api/agents

Returns a paginated list of agents. Accepts optional query parameters for filtering.

const res = await fetch(
  'https://clawdbase.ai/api/agents?verified=true&tier=high&limit=20'
)
const { data, total } = await res.json()

import httpx

r = httpx.get(
  'https://clawdbase.ai/api/agents',
  params={'verified': 'true', 'tier': 'high', 'limit': 20}
)
agents = r.json()['data']

curl "https://clawdbase.ai/api/agents?verified=true&tier=high&limit=20"

Query parameters

Parameter	Type	Description
`q`	`string`	Full-text search across name, description, creator
`verified`	`boolean`	`true` to return only MySanctum-verified entries
`tier`	`"high" \| "medium" \| "low"`	Filter by trust score tier
`category`	`string`	Agent category slug (e.g. `coding`, `research`)
`sort`	`"score_desc" \| "score_asc" \| "name"`	Sort order (default: `score_desc`)
`limit`	`number`	Page size, 1–100 (default: `20`)
`offset`	`number`	Pagination offset (default: `0`)

Response

{
  data: Agent[]
  total: number
  offset: number
  limit: number
}

Get an agent

GET /api/agents/:id

Returns the full detail record for a single agent by its AGT-XXXXXXXX ID.

const res = await fetch('https://clawdbase.ai/api/agents/AGT-a1b2c3d4')
const agent = await res.json()

console.log(agent.trustScore)    // 88
console.log(agent.confidence)    // 91
console.log(agent.verified)      // true

import httpx

agent = httpx.get('https://clawdbase.ai/api/agents/AGT-a1b2c3d4').json()
print(agent['trustScore'], agent['confidence'])

curl "https://clawdbase.ai/api/agents/AGT-a1b2c3d4"

Response shape

interface Agent {
  id: string           // "AGT-a1b2c3d4"
  type: 'agent' | 'skill'
  name: string
  description: string
  category: string
  tags: string[]
  creator: {
    handle: string
    displayName: string
    verified: boolean
    trustScore: number    // 0–100, null if unverified
    confidence: number    // 0–100, null if unverified
  }
  github: {
    url: string
    stars: number
    forks: number
    openIssues: number
    lastCommit: string   // ISO 8601
  } | null
  verified: boolean
  listedAt: string       // ISO 8601
  updatedAt: string
}

Get lineage

GET /api/agents/:id/lineage

Returns the full ancestor and descendant tree for an agent.

const res = await fetch('https://clawdbase.ai/api/agents/AGT-a1b2c3d4/lineage')
const { ancestors, descendants, depth } = await res.json()

import httpx

lineage = httpx.get(
  'https://clawdbase.ai/api/agents/AGT-a1b2c3d4/lineage'
).json()

curl "https://clawdbase.ai/api/agents/AGT-a1b2c3d4/lineage"

Response shape

interface LineageResponse {
  root: Agent
  ancestors: LineageNode[]
  descendants: LineageNode[]
  depth: number
}

interface LineageNode {
  agent: Agent
  parentId: string | null
  trustEquityFlow: number  // 0–100, equity inherited from parent
}

Identity & Scores

Get a creator's trust profile

GET /api/identity/:handle

Returns the trust score and verified account summary for a creator by their MySanctum handle.

const res = await fetch('https://clawdbase.ai/api/identity/openai')
const { trustScore, confidence, verifiedAccounts } = await res.json()

import httpx

profile = httpx.get('https://clawdbase.ai/api/identity/openai').json()

curl "https://clawdbase.ai/api/identity/openai"

Response shape

interface IdentityProfile {
  handle: string
  displayName: string
  trustScore: number
  confidence: number
  tier: 'high' | 'medium' | 'low'
  verifiedAccounts: {
    github?: boolean
    linkedin?: boolean
    npm?: boolean
    pypi?: boolean
  }
  agentCount: number
  trustEquity: number
}

Register an agent (authenticated)

POST /api/agents/register

Registers a new agent under your MySanctum identity. Requires a bearer token from your MySanctum account.

const res = await fetch('https://clawdbase.ai/api/agents/register', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${MYSANCTUM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    githubUrl: 'https://github.com/your-username/your-agent',
    name: 'My Research Agent',
    description: 'Synthesizes multi-source research into structured reports.',
    category: 'research',
    tags: ['research', 'synthesis', 'python', 'langchain'],
    parentId: 'AGT-a1b2c3d4',  // optional: set lineage parent
  }),
})

const { id, listingUrl } = await res.json()
console.log(`Listed at: ${listingUrl}`)  // https://clawdbase.ai/your-username/your-agent

import httpx

r = httpx.post(
  'https://clawdbase.ai/api/agents/register',
  headers={'Authorization': f'Bearer {MYSANCTUM_API_KEY}'},
  json={
    'githubUrl': 'https://github.com/your-username/your-agent',
    'name': 'My Research Agent',
    'description': 'Synthesizes multi-source research into structured reports.',
    'category': 'research',
    'tags': ['research', 'synthesis', 'python', 'langchain'],
  }
)
print(r.json()['id'])  # AGT-c9d0e1f2

curl -X POST "https://clawdbase.ai/api/agents/register" \
  -H "Authorization: Bearer $MYSANCTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "githubUrl": "https://github.com/your-username/your-agent",
    "name": "My Research Agent",
    "category": "research"
  }'

Request body

Field	Required	Description
`githubUrl`	✓	Public GitHub repository URL
`name`	✓	Display name in the directory
`description`	✓	Short description (max 280 chars)
`category`	✓	One of: `coding`, `research`, `productivity`, `data`, `automation`, `creative`, `infrastructure`, `communication`, `other`
`tags`	-	Array of strings, max 8
`parentId`	-	`AGT-XXXXXXXX` ID of the parent agent for lineage

Error responses

All errors follow a standard shape:

{
  error: string        // machine-readable code
  message: string      // human-readable description
  status: number       // HTTP status code
}

Common codes:

Status	Code	Meaning
`400`	`invalid_request`	Missing or malformed parameter
`401`	`unauthorized`	Missing or invalid bearer token
`404`	`not_found`	Agent or identity not found
`409`	`already_registered`	Agent is already registered
`429`	`rate_limited`	Too many requests - wait before retrying

Rate limits

Unauthenticated read endpoints: 120 requests / minute.
Authenticated write endpoints: 30 requests / minute per token.

Responses include standard X-RateLimit-* headers.

Get your API token from your MySanctum dashboard. Navigate to Settings → API Keys → Generate new key.

On this page