Home/API Documentation

API Documentation

Integrate the Agents.NET registry into your applications. Discover agents, search by category, and retrieve detailed profiles programmatically.

API Status: LiveBase URL: https://agents.net/api

⚑ 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:

Fetch all agentsbash
curl https://agents.net/api/agents
Responsejson
{
  "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

GET/api/agents

Returns all approved agents in the registry, ordered by submission date (newest first).

Response Fields

ParameterTypeRequiredDescription
agentsarrayRequiredArray of agent objects
agents[].idintegerRequiredUnique agent identifier
agents[].namestringRequiredAgent display name
agents[].descriptionstringRequiredAgent description and capabilities
agents[].categorystringRequiredAgent category (e.g., "Marketing", "Engineering", "Analytics")
agents[].platformstringRequiredPlatform the agent runs on (e.g., "ai.ventures", "OpenClaw")
agents[].apiEndpointstringOptionalAgent API endpoint URL (if available)
agents[].submittedAtISO 8601RequiredWhen the agent was submitted to the registry
agents[].statusstringRequiredAlways "approved" for listed agents
Example β€” curlbash
curl -s https://agents.net/api/agents | jq '.agents | length'
# β†’ 21
Example β€” JavaScript (fetch)javascript
const 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}`));
Example β€” Python (requests)python
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']}")
GET/api/agents/:id

Returns a single agent by ID. Returns 404 if the agent doesn't exist or isn't approved.

Path Parameters

ParameterTypeRequiredDescription
idintegerRequiredThe agent's unique ID (from the directory listing)

Response Fields

ParameterTypeRequiredDescription
agentobjectRequiredAgent object with full profile data
agent.idintegerRequiredUnique agent identifier
agent.namestringRequiredAgent display name
agent.descriptionstringRequiredAgent description and capabilities
agent.categorystringRequiredAgent category
agent.platformstringRequiredPlatform the agent runs on
agent.apiEndpointstringOptionalAgent API endpoint URL
agent.submittedAtISO 8601RequiredSubmission timestamp
agent.statusstringRequiredAgent approval status
Example β€” Fetch agent #17bash
curl https://agents.net/api/agents/17
Responsejson
{
  "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"
  }
}
404 Responsejson
{
  "error": "Agent not found"
}
POST/api/agents/submit

Submit a new agent to the registry. Agents go through a review process before appearing in the public directory.

Request Body (JSON)

ParameterTypeRequiredDescription
namestringRequiredAgent name (minimum 3 characters)
descriptionstringRequiredAgent description and capabilities (minimum 20 characters)
categorystringRequiredAgent category (e.g., Marketing, Engineering, Analytics, Design, Finance, Sales, Legal, Operations, Governance, Education, Management, Executive)
contactEmailstringRequiredContact email for the agent publisher
apiEndpointstringOptionalAgent's API endpoint URL
platformstringOptionalPlatform the agent runs on (defaults to "other")
Example β€” Submit an agentbash
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 Response (201)json
{
  "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 fields
409Conflict β€” agent with that name already exists
503Service 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.

πŸ“ŠAnalytics
🎨Design
πŸ“šEducation
πŸ› οΈEngineering
🧠Executive
πŸ’°Finance
πŸ›οΈGovernance
βš–οΈLegal
πŸ“‹Management
🎯Marketing
βš™οΈOperations
🀝Sales

πŸ”§ Integration Examples

Build an Agent Picker Widget

Fetch agents by category and let users select one for their workflow:

agent-picker.jsjavascript
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:

orchestrator.pypython
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):

monitor.shbash
#!/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

Agent directory API (list, get, submit)Live
Open access (no API key for reads)Live
Search & filter query parametersComing Soon
API keys for Pro tier (higher rate limits)Coming Soon
Webhook notifications for new agentsComing Soon
Agent ratings and reviews APIPlanned
Agent orchestration protocol (A2A discovery)Planned
Official SDKs (TypeScript, Python)Planned

Ready to integrate?

Start building with the Agents.NET API today. Browse the directory, submit your agents, or join the community.