Swarms API Documentation - Build AI Agents & Multi-Agent Systems

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

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:

string

required

The name of the agent (minimum 2 characters)

string

Agent code/content (minimum 5 characters if provided); can be null

string

required

A detailed description of what the agent does

string

Programming language used (e.g., “python”, “javascript”)

array

An array of package requirements

[
  {
    "package": "pandas",
    "installation": "pip install pandas"
  }
]

array

An array of use cases showing what your agent can do

[
  {
    "title": "Data Analysis",
    "description": "Analyze large datasets and generate insights"
  }
]

string

Comma-separated tags (minimum 2 characters if provided)

boolean

default:"true"

Whether the agent is free or paid

number

Price in USD (required if is_free is false, minimum: 0.01)

string

The agent’s category (e.g., “data-science”, “automation”)

string

default:"pending"

The status of the agent (pending, approved, rejected)

string

Public image URL (valid URL or empty string)

string

Storage path for image (alternative to image_url)

string

Base64-encoded image (alternative to image_url; can include data:image/...;base64, prefix)

array

Links: array of strings or { "name": string, "url": string } (e.g. website, twitter, telegram for token metadata)

string

Seller wallet address

string

x402 payment URL (valid URL or empty string)

string

MCP server URL (valid URL or empty string)

boolean

Enable tokenization on Solana

string

Required when tokenized_on is true; uppercase letters and numbers only; max 10 characters

string

Creator wallet public key; required when tokenized_on is true

string

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:

{
  "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

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"
  }'

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())

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:

string

required

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"
  }'

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())

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

{
  "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

string

Keyword to match agent names/descriptions

string

Filter by category (case-insensitive)

string

default:"all"

Filter by price: “all”, “free”, or “paid”

string

Filter by user ID

string

default:"newest"

Sort order: “newest”, “oldest”, “popular”, or “rating”

number

default:"6"

Number of agents to return (1-100)

number

default:"0"

Offset for pagination

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
  }'

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)

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

[
  {
    "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: 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:

{
  "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!

Platform

Fiat Payments

Launchpad

API

Examples

Resources

Agents API

Step 1: Authentication

Base URL

Step 2: Create an Agent

Endpoint

Input schema (Add Agent)

Request Body (detailed)

Validation rules

Success response (200)

Output schema (Add Agent — success)

Error responses (Add Agent)

Error output schema (common fields)

Example Request

Step 3: Update or Query Agents

Update Agent

Endpoint

Request Body

Example Request

Success Response

Query Agents

Endpoint

Request Body

Example Request

Example Response

Rate Limiting

Error Responses

Example Error Response

Content Validation

​Step 1: Authentication

​Base URL

​Step 2: Create an Agent

​Endpoint

​Input schema (Add Agent)

​Request Body (detailed)

​Validation rules

​Success response (200)

​Output schema (Add Agent — success)

​Error responses (Add Agent)

​Error output schema (common fields)

​Example Request

​Step 3: Update or Query Agents

​Update Agent

​Endpoint

​Request Body

​Example Request

​Success Response

​Query Agents

​Endpoint

​Request Body

​Example Request

​Example Response

​Rate Limiting

​Error Responses

​Example Error Response

​Content Validation

Step 1: Authentication

Base URL

Step 2: Create an Agent

Endpoint

Input schema (Add Agent)

Request Body (detailed)

Validation rules

Success response (200)

Output schema (Add Agent — success)

Error responses (Add Agent)

Error output schema (common fields)

Example Request

Step 3: Update or Query Agents

Update Agent

Endpoint

Request Body

Example Request

Success Response

Query Agents

Endpoint

Request Body

Example Request

Example Response

Rate Limiting

Error Responses

Example Error Response

Content Validation