Authentication
All prompt management endpoints require authentication using one of the following methods:- API Key: Include your API key in the
Authorizationheader asBearer <your-api-key> - Supabase Session: Include your Supabase session token in the
Authorizationheader
Base URL
Create Prompt
Create a new prompt in the marketplace.Endpoint
Input schema (Add Prompt)
Request Body (detailed)
Links: array of strings or
{ "name": string, "url": string } (e.g. website, twitter, telegram for token metadata)Validation rules
- Paid prompts: 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.
Success response (200)
tokenized is true and token_address and pool_address are set.
Output schema (Add Prompt — success)
Error responses (Add Prompt)
- 400 – Validation:
error,message,details,errors,status_code. Content validation: alsotrustworthiness,contentQuality. Duplicate:existingId. Tokenization failed: standard 400 shape. - 401 –
error,message,details,how_to_get_key,status_code(e.g. API key missing, invalid/expired, user not found). - 429 –
error,message,details,currentUsage,limits,resetTime,status_code. - 500 – Server/database/tokenization error:
error,message,details,status_code(may includehint,codefor DB errors).
Error output schema (common fields)
Example Request
Update Prompt
Update an existing prompt in the marketplace.Endpoint
Request Body
All fields from the create prompt endpoint are available, plus:Response
Example Request
Query Prompts
Search and filter prompts in the marketplace.Endpoint
Request Body
Only approved prompts are returned.Response
Example Request
Query Parameters Explained
- prompt_id: Returns the single prompt with this ID (
query_type: "id") - username: Returns the prompts owned by this username (
query_type: "username"); a404is returned when the username does not exist - prompt_name: Matches prompt names as a substring/slug (
query_type: "slug"); dashes are treated as wildcards - limit: Caps the number of results (1–100, default 20)
Rate Limiting
All prompt management endpoints are subject to rate limiting:- Daily Limit: 500 prompts per user per day
- Reset Time: Midnight
- Free Content Limit: 500 free items (prompts + agents) per day
- Paid Content Limit: 500 paid prompts per day
429 error response:
Error Responses
The API returns standard HTTP status codes:200: Success400: Bad Request (validation errors)401: Unauthorized (authentication required)403: Forbidden (paid content without access)404: Not Found429: Too Many Requests (rate limit exceeded)500: Internal Server Error
Example Error Response
All endpoints return consistent error responses:details, errors, and status_code. Duplicate content responses include existingId. Rate limit (429) responses include currentUsage, limits, and resetTime. Authentication (401) responses may include how_to_get_key.
Common Validation Errors
- Prompt name less than 2 characters
- Prompt content less than 5 characters
- Invalid URL format for
image_urlor links - Missing
price_usdwhenis_freeis false - Invalid use case format (missing title or description)
- Duplicate content: response includes
existingIdwith the existing prompt ID - Tokenization: when
tokenized_onis true, missing or invalidticker,creator_wallet, orprivate_key
Content Validation
All prompts undergo automatic validation for:- Duplicate Detection: Same name and same prompt content for the same user returns 400 with
existingId - Quality Assessment: Evaluates prompt clarity and completeness (responses may include
trustworthiness,contentQuality) - Content Safety: Ensures prompts don’t contain harmful or inappropriate content
- Trustworthiness Scoring: Assigns a score based on various quality factors
400 Bad Request response with details about the validation failure.
Validation Response Example (duplicate)
Price Conversion
When you submit a prompt withprice_usd, the system automatically converts it to SOL (Solana) based on the current market price. The converted price is stored in the price field.
Example:
- You set
price_usd: 10.00 - Current SOL price: $200
- Calculated
price: 0.05 SOL
Database Schema
Prompts are stored with the following key fields:Using Marketplace Prompts with Agents
Once you have a prompt in the marketplace, you can use it with any agent by specifying themarketplace_prompt_id in the agent configuration. The Swarms API will automatically retrieve the prompt from the marketplace and apply it to your agent.
How It Works
- Query the marketplace to find a suitable prompt using the Query Prompts endpoint
- Copy the prompt’s
idfrom the response - Use the
marketplace_prompt_idfield in your agent configuration - The system automatically retrieves and applies the prompt to your agent
Example: Using a Marketplace Prompt
Direct Usage with Known Prompt ID
If you already know the prompt ID, you can use it directly:Important Notes
- When
marketplace_prompt_idis provided, it takes precedence over thesystem_promptfield - The prompt is automatically retrieved from the marketplace and applied to the agent
- You don’t need to manually fetch or pass the prompt content
- Both free and paid marketplace prompts can be used with agents
- For more details on agent configuration, see the Agent Completions Reference