> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agents API > Easily create, update, and fetch agents in the Swarms marketplace in just 3 steps Managing AI agents in the Swarms marketplace is simple—just follow **3 easy steps**: 1. **Authenticate**: Secure your requests with an API key or Supabase session token. 2. **Create, Update, or Query Agents**: Use the endpoints below to add, modify, or search agents. 3. **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 `. * **Supabase Session**: Provide your Supabase session token in the `Authorization` header. ## Base URL ``` https://swarms.world ``` *** ## Step 2: Create an Agent It's quick and easy to create your own agent in the marketplace. ### Endpoint ``` POST /api/add-agent ``` ### Input schema (Add Agent) | Parameter | Type | Required | Description | | ----------------------- | ------- | ------------ | ---------------------------------------------------------------------------------------------- | | `name` | string | Yes | Display name (min 2 characters) | | `agent` | string | No | Agent code/content (min 5 characters if provided); can be null | | `language` | string | No | Programming or script language | | `description` | string | Yes | Description of the agent | | `requirements` | array | No | Dependencies; each `{ "package": string, "installation": string }` | | `useCases` | array | Yes | Use cases; each `{ "title": string, "description": string }` | | `tags` | string | No | Comma-separated tags (min 2 characters if provided) | | `is_free` | boolean | No | Default `true` | | `price_usd` | number | If paid | Required when `is_free` is false; must be > 0 | | `category` | string | No | Optional category | | `status` | string | No | `'pending'` \| `'approved'` \| `'rejected'`; default `'pending'` | | `tokenized_on` | boolean | No | Enable tokenization on Solana | | `ticker` | string | If tokenized | Required when `tokenized_on` is true; uppercase alphanumeric; max 10 characters | | `image_url` | string | No | Public image URL (valid URL or empty string) | | `file_path` | string | No | Storage path for image (alternative to `image_url`) | | `image_base64` | string | No | Base64-encoded image (alternative to `image_url`; may include `data:image/...;base64,` prefix) | | `links` | array | No | Array of strings or `{ "name": string, "url": string }` | | `seller_wallet_address` | string | No | Seller wallet address | | `x402_url` | string | No | x402 payment URL (valid URL or empty string) | | `mcp_url` | string | No | MCP server URL (valid URL or empty string) | | `creator_wallet` | string | If tokenized | Creator wallet public key; required when `tokenized_on` is true | | `private_key` | string | If tokenized | Private key for signing (JSON array or base64); required when `tokenized_on` is true | ### Request Body (detailed) Just provide the necessary agent details: The name of the agent (minimum 2 characters) Agent code/content (minimum 5 characters if provided); can be null A detailed description of what the agent does Programming language used (e.g., "python", "javascript") An array of package requirements ```json theme={null} [ { "package": "pandas", "installation": "pip install pandas" } ] ``` An array of use cases showing what your agent can do ```json theme={null} [ { "title": "Data Analysis", "description": "Analyze large datasets and generate insights" } ] ``` Comma-separated tags (minimum 2 characters if provided) 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) Public image URL (valid URL or empty string) Storage path for image (alternative to `image_url`) Base64-encoded image (alternative to `image_url`; can include `data:image/...;base64,` prefix) Links: array of strings or `{ "name": string, "url": string }` (e.g. website, twitter, telegram for token metadata) Seller wallet address x402 payment URL (valid URL or empty string) MCP server URL (valid URL or empty string) Enable tokenization on Solana Required when `tokenized_on` is true; uppercase letters and numbers only; max 10 characters Creator wallet public key; required when `tokenized_on` is true Private key for signing (JSON array or base64); required when `tokenized_on` is true ### Validation rules * **Paid agents**: When `is_free` is `false`, `price_usd` is required and must be > 0. * **Tokenization**: When `tokenized_on` is `true`, `ticker`, `creator_wallet`, and `private_key` are required; ticker must be uppercase alphanumeric, max 10 characters. * **Duplicate**: Same name and same `agent` content for the same user returns 400 with `existingId`. ### Success response (200) On success, you'll immediately get: ```json theme={null} { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440000", "tokenized": false, "token_address": null, "pool_address": null } ``` When tokenization is used, `tokenized` is `true` and `token_address` and `pool_address` are set. ### Output schema (Add Agent — success) | Field | Type | Description | | --------------- | -------------- | ----------------------------------------------------------------- | | `success` | boolean | `true` on success | | `id` | string | UUID of the created agent | | `listing_url` | string | URL to the agent listing (e.g. `https://swarms.world/agent/{id}`) | | `tokenized` | boolean | Whether the agent was tokenized | | `token_address` | string \| null | Solana token address (when tokenized) | | `pool_address` | string \| null | Liquidity pool address (when tokenized) | ### Error responses (Add Agent) * **400** – Validation: `error`, `message`, `details`, `errors`, `status_code`. Content validation: also `trustworthiness`, `contentQuality`. Duplicate agent: `existingId`. Tokenization failed: standard 400 shape. * **401** – `error`, `message`, `details`, `how_to_get_key`, `status_code`. * **429** – `error`, `message`, `details`, `currentUsage`, `limits`, `resetTime`, `status_code`. * **500** – Server/database/price conversion/tokenization error: `error`, `message`, `details`, `status_code` (may include `hint`, `code` for DB errors). ### Error output schema (common fields) | HTTP | Field | Type | Description | | ---- | ----------------- | ------ | ------------------------------------------------------------------- | | All | `error` | string | Short error message | | All | `message` | string | Detailed description | | All | `code` | string | Error code (e.g. `VALIDATION_ERROR`) | | All | `details` | string | Optional extra context | | All | `status_code` | number | HTTP status code | | 400 | `errors` | object | Validation errors by field | | 400 | `existingId` | string | Existing agent ID (duplicate) | | 400 | `trustworthiness` | number | Content trust score (content validation) | | 400 | `contentQuality` | number | Content quality score (content validation) | | 401 | `how_to_get_key` | string | Instructions to obtain API key | | 429 | `currentUsage` | object | Current usage counts | | 429 | `limits` | object | Rate limit values | | 429 | `resetTime` | string | ISO timestamp when limit resets | | 500 | `hint` | string | Optional DB/system hint (DB errors may also include a `code` field) | ### Example Request ```bash cURL theme={null} 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" }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/add-agent" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } data = { "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" } ], "tags": "data,analysis,python,ml,ai", "is_free": False, "price_usd": 19.99, "category": "data-science", "seller_wallet_address": "your-wallet-address" } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch('https://swarms.world/api/add-agent', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ 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' } ], tags: 'data,analysis,python,ml,ai', is_free: false, price_usd: 19.99, category: 'data-science', seller_wallet_address: 'your-wallet-address' }) }); const data = await response.json(); console.log(data); ``` *** ## 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 ``` POST /api/edit-agent ``` #### Request Body All fields from the create agent endpoint are available, plus: The unique ID of the agent you want to update #### Example Request ```bash cURL theme={null} 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" }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/edit-agent" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } data = { "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" } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch('https://swarms.world/api/edit-agent', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ 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' }) }); const data = await response.json(); console.log(data); ``` #### Success Response ```json theme={null} { "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 ``` POST /api/query-agents ``` #### Request Body Keyword to match agent names/descriptions Filter by category (case-insensitive) Filter by price: "all", "free", or "paid" Filter by user ID Sort order: "newest", "oldest", "popular", or "rating" Number of agents to return (1-100) Offset for pagination #### Example Request ```bash cURL theme={null} 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 }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/query-agents" headers = {"Content-Type": "application/json"} data = { "search": "data analysis", "category": "data-science", "priceFilter": "all", "sortBy": "newest", "limit": 10, "offset": 0 } response = requests.post(url, json=data, headers=headers) agents = response.json() print(agents) ``` ```javascript JavaScript theme={null} const response = await fetch('https://swarms.world/api/query-agents', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ search: 'data analysis', category: 'data-science', priceFilter: 'all', sortBy: 'newest', limit: 10, offset: 0 }) }); const agents = await response.json(); console.log(agents); ``` #### Example Response ```json theme={null} [ { "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: ```json theme={null} { "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`: Success * `400`: Bad Request (validation errors) * `401`: Unauthorized * `403`: Forbidden (content validation failed) * `404`: Not Found * `429`: Too Many Requests * `500`: Internal Server Error ### Example Error Response All endpoints return consistent error responses: ```json theme={null} { "error": "Error message", "message": "Detailed error description", "code": "ERROR_CODE" } ``` Validation errors may include `details`, `errors`, and `status_code`. Duplicate agent responses include `existingId`. Rate limit (429) responses include `currentUsage`, `limits`, and `resetTime`. Authentication (401) responses may include `how_to_get_key`. *** ## Content Validation Every agent undergoes automated checks, including: * **Duplicate Detection**: Same name and same `agent` content for the same user returns 400 with `existingId` * **Quality Assessment**: Checks code completeness and standards * **Security Scanning**: Ensures code is safe * **Trustworthiness Scoring**: Rates each agent on quality and trust (content validation responses may include `trustworthiness`, `contentQuality`) Agents failing validation will get a `403 Forbidden` or `400 Bad Request` with detailed reasons. *** **In summary: you can create, edit, or search for agents in the Swarms marketplace in just 3 easy steps!**