Managing AI agents in the Swarms marketplace is simple—just follow 3 easy steps:
- Authenticate: Secure your requests with an API key or Supabase session token.
- Create, Update, or Query Agents: Use the endpoints below to add, modify, or search agents.
- Get Results or Listings: Instantly receive confirmation, your agent listing URL, or search results.
Step 1: Authentication
All agent management actions require authentication using one of these methods:
- API Key: Send your API key in the
Authorization header as Bearer <your-api-key>.
- Supabase Session: Provide your Supabase session token in the
Authorization header.
Base URL
Step 2: Create an Agent
It’s quick and easy to create your own agent in the marketplace.
Endpoint
Request Body
Just provide the necessary agent details:
The name of the agent (minimum 2 characters)
The agent code or configuration (minimum 5 characters)
A detailed description of what the agent does
Programming language used (e.g., “python”, “javascript”)
An array of package requirements[
{
"package": "pandas",
"installation": "pip install pandas"
}
]
An array of use cases showing what your agent can do[
{
"title": "Data Analysis",
"description": "Analyze large datasets and generate insights"
}
]
Comma-separated tags for categorization (e.g., “data,analysis,python”)
Whether the agent is free or paid
Price in USD (required if is_free is false, minimum: 0.01)
The agent’s category (e.g., “data-science”, “automation”)
The status of the agent (pending, approved, rejected)
URL to an image representing your agent
Path to any associated files
An array of relevant links (docs, repo, etc.)
Wallet address for payments (for paid agents)
Whether the agent is tokenized on blockchain
Response
On success, you’ll immediately get:
{
"success": true,
"id": "550e8400-e29b-41d4-a716-446655440000",
"listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440000"
}
Example Request
curl -X POST https://swarms.world/api/add-agent \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Data Analysis Agent",
"agent": "from swarms import Agent\n\nclass DataAnalysisAgent(Agent):\n def analyze(self, data):\n # Analysis logic here\n pass",
"description": "An AI agent specialized in analyzing large datasets and generating actionable insights",
"language": "python",
"requirements": [
{
"package": "pandas",
"installation": "pip install pandas"
},
{
"package": "numpy",
"installation": "pip install numpy"
}
],
"useCases": [
{
"title": "Financial Data Analysis",
"description": "Analyze financial statements and market trends"
},
{
"title": "Customer Behavior Analysis",
"description": "Identify patterns in customer data"
}
],
"tags": "data,analysis,python,ml,ai",
"is_free": false,
"price_usd": 19.99,
"category": "data-science",
"seller_wallet_address": "your-wallet-address"
}'
Step 3: Update or Query Agents
You can easily change agent info or search/filter agents—just as effortlessly as creating one!
Update Agent
Endpoint
Request Body
All fields from the create agent endpoint are available, plus:
The unique ID of the agent you want to update
Example Request
curl -X POST https://swarms.world/api/edit-agent \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Advanced Data Analysis Agent",
"description": "Updated description with new capabilities",
"price_usd": 24.99,
"tags": "data,analysis,python,ml,ai,advanced"
}'
Success Response
{
"success": true,
"id": "550e8400-e29b-41d4-a716-446655440000",
"listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440000",
"updated_data": {
// Updated agent fields
}
}
Query Agents
Endpoint
Request Body
Keyword to match agent names/descriptions
Filter by category (case-insensitive)
Filter by price: “all”, “free”, or “paid”
Sort order: “newest”, “oldest”, “popular”, or “rating”
Number of agents to return (1-100)
Example Request
curl -X POST https://swarms.world/api/query-agents \
-H "Content-Type: application/json" \
-d '{
"search": "data analysis",
"category": "data-science",
"priceFilter": "all",
"sortBy": "newest",
"limit": 10,
"offset": 0
}'
Example Response
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Data Analysis Agent",
"agent": "Agent code here...",
"description": "An AI agent specialized in data analysis",
"language": "python",
"requirements": [
{
"package": "pandas",
"installation": "pip install pandas"
}
],
"use_cases": [
{
"title": "Financial Analysis",
"description": "Analyze financial data"
}
],
"tags": "data,analysis,python",
"is_free": false,
"price_usd": 19.99,
"price": 0.05,
"category": "data-science",
"status": "approved",
"image_url": "https://example.com/image.jpg",
"user_id": "user-123",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
]
Rate Limiting
All agent management endpoints are subject to rate limiting:
- Daily Limit: 500 agents per user per day
- Reset Time: Midnight UTC
If you exceed the limit, you’ll receive a 429 error response:
{
"error": "Daily limit exceeded",
"message": "Daily limit reached: 500 agents per day. Resets at midnight.",
"currentUsage": {
"paidAgents": 500,
"paidPrompts": 0,
"freeContent": 0,
"date": "2024-01-01"
},
"limits": {
"paidAgents": 500,
"paidPrompts": 500,
"freeContent": 500
},
"resetTime": "2024-01-02T00:00:00.000Z"
}
Error Responses
The API uses standard HTTP status codes to signal errors:
200: Success400: Bad Request (validation errors)401: Unauthorized403: Forbidden (content validation failed)404: Not Found429: Too Many Requests500: Internal Server Error
Example Error Response
{
"error": "Validation error",
"message": "Agent name must be at least 2 characters long",
"code": "VALIDATION_ERROR"
}
Content Validation
Every agent undergoes automated checks, including:
- Duplicate Detection: No duplicate agents per user
- Quality Assessment: Checks code completeness and standards
- Security Scanning: Ensures code is safe
- Trustworthiness Scoring: Rates each agent on quality and trust
Agents failing validation will get a 403 Forbidden with detailed reasons.
In summary: you can create, edit, or search for agents in the Swarms marketplace in just 3 easy steps! 
