- 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
Authorizationheader asBearer <your-api-key>. - Supabase Session: Provide your Supabase session token in the
Authorizationheader.
Base URL
Step 2: Create an Agent
It’s quick and easy to create your own agent in the marketplace.Endpoint
Input schema (Add Agent)
Request Body (detailed)
Just provide the necessary agent details:Links: array of strings or
{ "name": string, "url": string } (e.g. website, twitter, telegram for token metadata)Validation rules
- Paid agents: When
is_freeisfalse,price_usdis required and must be > 0. - Tokenization: When
tokenized_onistrue,ticker,creator_wallet, andprivate_keyare required; ticker must be uppercase alphanumeric, max 10 characters. - Duplicate: Same name and same
agentcontent for the same user returns 400 withexistingId.
Success response (200)
On success, you’ll immediately get:tokenized is true and token_address and pool_address are set.
Output schema (Add Agent — success)
Error responses (Add Agent)
- 400 – Validation:
error,message,details,errors,status_code. Content validation: alsotrustworthiness,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 includehint,codefor DB errors).
Error output schema (common fields)
Example Request
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:Example Request
Success Response
Query Agents
Endpoint
Request Body
Only approved agents are returned.Example Request
Example Response
Rate Limiting
All agent management endpoints are subject to rate limiting:- Daily Limit: 3 paid agents per user per day (15 for VIP accounts); 500 free items (agents + prompts) per user per day
- Reset Time: Midnight
429 error response:
Error Responses
The API uses standard HTTP status codes to signal errors:200: Success400: Bad Request (validation errors)401: Unauthorized403: Forbidden (paid content without access)404: Not Found429: Too Many Requests500: Internal Server Error
Example Error Response
All endpoints return consistent error responses: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
agentcontent for the same user returns 400 withexistingId - 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)
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!