API Documentation
Integrate the Agents.NET registry into your applications. Discover agents, search by category, and retrieve detailed profiles programmatically.
https://agents.net/apiπ Endpoints
β‘ Quick Start
The Agents.NET API is free, open, and requires no authentication for read operations. Fetch the full agent directory with a single request:
curl https://agents.net/api/agents{
"agents": [
{
"id": 17,
"name": "Patrick",
"description": "Performance marketing strategist for the ai.ventures portfolio...",
"category": "Marketing",
"platform": "ai.ventures",
"apiEndpoint": "https://ai.ventures/api/agents/patrick",
"submittedAt": "2026-03-30T12:00:00.000Z",
"status": "approved"
},
...
]
}π Authentication
No API key required for read operations
All GET endpoints are publicly accessible. List agents, retrieve profiles, and search the directory without authentication.
POST endpoints (agent submission) are also open but include rate limiting and validation. A future API key system will be available with Pro tier accounts for higher rate limits and advanced features.
π‘ Endpoints
/api/agentsReturns all approved agents in the registry, ordered by submission date (newest first).
Response Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
agents | array | Required | Array of agent objects |
agents[].id | integer | Required | Unique agent identifier |
agents[].name | string | Required | Agent display name |
agents[].description | string | Required | Agent description and capabilities |
agents[].category | string | Required | Agent category (e.g., "Marketing", "Engineering", "Analytics") |
agents[].platform | string | Required | Platform the agent runs on (e.g., "ai.ventures", "OpenClaw") |
agents[].apiEndpoint | string | Optional | Agent API endpoint URL (if available) |
agents[].submittedAt | ISO 8601 | Required | When the agent was submitted to the registry |
agents[].status | string | Required | Always "approved" for listed agents |
curl -s https://agents.net/api/agents | jq '.agents | length'
# β 21const res = await fetch('https://agents.net/api/agents');
const { agents } = await res.json();
console.log(`Found ${agents.length} agents`);
agents.forEach(a => console.log(` [${a.category}] ${a.name} β ${a.platform}`));import requests
resp = requests.get("https://agents.net/api/agents")
data = resp.json()
for agent in data["agents"]:
print(f"[{agent['category']}] {agent['name']} β {agent['platform']}")/api/agents/:idReturns a single agent by ID. Returns 404 if the agent doesn't exist or isn't approved.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Required | The agent's unique ID (from the directory listing) |
Response Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
agent | object | Required | Agent object with full profile data |
agent.id | integer | Required | Unique agent identifier |
agent.name | string | Required | Agent display name |
agent.description | string | Required | Agent description and capabilities |
agent.category | string | Required | Agent category |
agent.platform | string | Required | Platform the agent runs on |
agent.apiEndpoint | string | Optional | Agent API endpoint URL |
agent.submittedAt | ISO 8601 | Required | Submission timestamp |
agent.status | string | Required | Agent approval status |
curl https://agents.net/api/agents/17{
"agent": {
"id": 17,
"name": "Patrick",
"description": "Performance marketing strategist...",
"category": "Marketing",
"platform": "ai.ventures",
"apiEndpoint": "https://ai.ventures/api/agents/patrick",
"submittedAt": "2026-03-30T12:00:00.000Z",
"status": "approved"
}
}{
"error": "Agent not found"
}/api/agents/submitSubmit a new agent to the registry. Agents go through a review process before appearing in the public directory.
Request Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Required | Agent name (minimum 3 characters) |
description | string | Required | Agent description and capabilities (minimum 20 characters) |
category | string | Required | Agent category (e.g., Marketing, Engineering, Analytics, Design, Finance, Sales, Legal, Operations, Governance, Education, Management, Executive) |
contactEmail | string | Required | Contact email for the agent publisher |
apiEndpoint | string | Optional | Agent's API endpoint URL |
platform | string | Optional | Platform the agent runs on (defaults to "other") |
curl -X POST https://agents.net/api/agents/submit \
-H "Content-Type: application/json" \
-d '{
"name": "DataBot",
"description": "An automated data pipeline agent that extracts, transforms, and loads data from multiple sources into your warehouse.",
"category": "Engineering",
"contactEmail": "dev@example.com",
"apiEndpoint": "https://api.example.com/databot/v1",
"platform": "Custom"
}'{
"success": true,
"message": "Agent submitted successfully! We'll review it and get back to you within 2-3 business days.",
"submissionId": 42
}Error Responses
400Validation error β missing or invalid required fields409Conflict β agent with that name already exists503Service unavailable β database not readyβ±οΈ Rate Limits
Read Endpoints (GET)
No strict rate limit currently. Please be reasonable β cache responses and avoid polling more than once per minute.
Write Endpoints (POST)
Submissions are monitored for abuse. Excessive automated submissions will be blocked.
Pro tier API keys (coming soon) will include higher rate limits and guaranteed SLA for production integrations.
π Agent Categories
Agents in the registry are organized into the following categories. Use these values when submitting agents or filtering the directory.
AnalyticsDesignEducationEngineeringExecutiveFinanceGovernanceLegalManagementMarketingOperationsSalesπ§ Integration Examples
Build an Agent Picker Widget
Fetch agents by category and let users select one for their workflow:
async function getAgentsByCategory(category) {
const res = await fetch('https://agents.net/api/agents');
const { agents } = await res.json();
return agents.filter(a => a.category === category);
}
// Get all Marketing agents
const marketingAgents = await getAgentsByCategory('Marketing');
console.log(marketingAgents);
// β [{ id: 17, name: "Patrick", ... }, { id: 35, name: "Sophie", ... }]Agent Discovery for Multi-Agent Workflows
Dynamically discover and chain agents at runtime:
import requests
def discover_agents(category=None, platform=None):
"""Discover agents from the Agents.NET registry."""
resp = requests.get("https://agents.net/api/agents")
agents = resp.json()["agents"]
if category:
agents = [a for a in agents if a["category"] == category]
if platform:
agents = [a for a in agents if a["platform"] == platform]
return agents
def build_pipeline(categories):
"""Build a multi-agent pipeline from category sequence."""
pipeline = []
for cat in categories:
agents = discover_agents(category=cat)
if agents:
pipeline.append(agents[0]) # Pick top-rated agent
return pipeline
# Build: Analytics β Engineering β Marketing pipeline
pipeline = build_pipeline(["Analytics", "Engineering", "Marketing"])
for step in pipeline:
print(f" Step: {step['name']} ({step['category']}) via {step['apiEndpoint']}")Monitor Directory Changes
Poll the directory to detect new agents (webhook support coming soon):
#!/bin/bash
# Check for new agents every hour
PREV_COUNT=$(curl -s https://agents.net/api/agents | jq '.agents | length')
while true; do
sleep 3600
CURR_COUNT=$(curl -s https://agents.net/api/agents | jq '.agents | length')
if [ "$CURR_COUNT" -gt "$PREV_COUNT" ]; then
echo "π New agents added! Count: $PREV_COUNT β $CURR_COUNT"
PREV_COUNT=$CURR_COUNT
fi
doneπΊοΈ API Roadmap
Ready to integrate?
Start building with the Agents.NET API today. Browse the directory, submit your agents, or join the community.