> ## 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. # Prompts API > Learn how to create, update, and fetch prompts in the Swarms marketplace The Prompts API allows you to manage AI prompts in the Swarms marketplace. You can create new prompts, update existing ones, and query prompts with various filters. ## Authentication All prompt management endpoints require authentication using one of the following methods: * **API Key**: Include your API key in the `Authorization` header as `Bearer ` * **Supabase Session**: Include your Supabase session token in the `Authorization` header ## Base URL ``` https://swarms.world ``` *** ## Create Prompt Create a new prompt in the marketplace. ### Endpoint ``` POST /api/add-prompt ``` ### Input schema (Add Prompt) | Parameter | Type | Required | Description | | ----------------------- | ------- | ------------ | ---------------------------------------------------------------------------------------------- | | `name` | string | Yes | Display name (min 2 characters) | | `prompt` | string | Yes | Prompt content (min 5 characters) | | `description` | string | No | Optional description | | `useCases` | array | Yes | At least one use case; each `{ "title": string, "description": string }` | | `tags` | string | Yes | Comma-separated tags (min 2 characters) | | `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 | | `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) The name of the prompt (minimum 2 characters) The prompt content (minimum 5 characters) A detailed description of what the prompt does and when to use it An array of use cases demonstrating the prompt's applications ```json theme={null} [ { "title": "Content Generation", "description": "Generate blog posts and articles" } ] ``` Comma-separated tags (minimum 2 characters) Whether the prompt is free or paid Price in USD (required if `is_free` is false, minimum: 0.01) The category of the prompt (e.g., "content", "code", "analysis") The status of the prompt (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 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 prompts**: 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. ### Success response (200) ```json theme={null} { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "listing_url": "https://swarms.world/prompt/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 Prompt — success) | Field | Type | Description | | --------------- | -------------- | ------------------------------------------------------------------- | | `success` | boolean | `true` on success | | `id` | string | UUID of the created prompt | | `listing_url` | string | URL to the prompt listing (e.g. `https://swarms.world/prompt/{id}`) | | `tokenized` | boolean | Whether the prompt was tokenized | | `token_address` | string \| null | Solana token address (when tokenized) | | `pool_address` | string \| null | Liquidity pool address (when tokenized) | ### Error responses (Add Prompt) * **400** – Validation: `error`, `message`, `details`, `errors`, `status_code`. Content validation: also `trustworthiness`, `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 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 prompt 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-prompt \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Technical Blog Writer", "prompt": "You are an expert technical writer who creates comprehensive, well-structured blog posts about software engineering topics. Your writing is clear, accurate, and engaging. When given a topic, you:\n\n1. Research the subject thoroughly\n2. Create a logical outline\n3. Write in-depth explanations with examples\n4. Include code snippets where relevant\n5. Conclude with key takeaways\n\nTopic: {topic}", "description": "A prompt for generating high-quality technical blog posts with clear explanations and practical examples", "useCases": [ { "title": "Tutorial Creation", "description": "Generate step-by-step technical tutorials" }, { "title": "Concept Explanation", "description": "Explain complex technical concepts in simple terms" }, { "title": "Documentation Writing", "description": "Create comprehensive technical documentation" } ], "tags": "writing,technical,blog,documentation,content", "is_free": false, "price_usd": 4.99, "category": "content", "seller_wallet_address": "your-wallet-address" }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/add-prompt" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } data = { "name": "Technical Blog Writer", "prompt": """You are an expert technical writer who creates comprehensive, well-structured blog posts about software engineering topics. Your writing is clear, accurate, and engaging. When given a topic, you: 1. Research the subject thoroughly 2. Create a logical outline 3. Write in-depth explanations with examples 4. Include code snippets where relevant 5. Conclude with key takeaways Topic: {topic}""", "description": "A prompt for generating high-quality technical blog posts with clear explanations and practical examples", "useCases": [ { "title": "Tutorial Creation", "description": "Generate step-by-step technical tutorials" }, { "title": "Concept Explanation", "description": "Explain complex technical concepts in simple terms" } ], "tags": "writing,technical,blog,documentation,content", "is_free": False, "price_usd": 4.99, "category": "content", "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-prompt', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Technical Blog Writer', prompt: `You are an expert technical writer who creates comprehensive, well-structured blog posts about software engineering topics. Your writing is clear, accurate, and engaging. When given a topic, you: 1. Research the subject thoroughly 2. Create a logical outline 3. Write in-depth explanations with examples 4. Include code snippets where relevant 5. Conclude with key takeaways Topic: {topic}`, description: 'A prompt for generating high-quality technical blog posts with clear explanations and practical examples', useCases: [ { title: 'Tutorial Creation', description: 'Generate step-by-step technical tutorials' }, { title: 'Concept Explanation', description: 'Explain complex technical concepts in simple terms' } ], tags: 'writing,technical,blog,documentation,content', is_free: false, price_usd: 4.99, category: 'content', seller_wallet_address: 'your-wallet-address' }) }); const data = await response.json(); console.log(data); ``` *** ## Update Prompt Update an existing prompt in the marketplace. ### Endpoint ``` POST /api/edit-prompt ``` ### Request Body All fields from the create prompt endpoint are available, plus: The unique identifier of the prompt to update ### Response ```json theme={null} { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "listing_url": "https://swarms.world/prompt/550e8400-e29b-41d4-a716-446655440000", "updated_data": { // Updated prompt fields } } ``` ### Example Request ```bash cURL theme={null} curl -X POST https://swarms.world/api/edit-prompt \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Advanced Technical Blog Writer", "description": "Enhanced version with additional formatting capabilities", "price_usd": 6.99, "tags": "writing,technical,blog,documentation,content,advanced" }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/edit-prompt" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } data = { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Advanced Technical Blog Writer", "description": "Enhanced version with additional formatting capabilities", "price_usd": 6.99, "tags": "writing,technical,blog,documentation,content,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-prompt', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ id: '550e8400-e29b-41d4-a716-446655440000', name: 'Advanced Technical Blog Writer', description: 'Enhanced version with additional formatting capabilities', price_usd: 6.99, tags: 'writing,technical,blog,documentation,content,advanced' }) }); const data = await response.json(); console.log(data); ``` *** ## Query Prompts Search and filter prompts in the marketplace. ### Endpoint ``` POST /api/query-prompts ``` ### Request Body Search query to match against prompt names and descriptions (max 100 characters) Filter by category (case-insensitive, max 50 characters) Filter by price type: "all", "free", or "paid" Filter by specific user ID Sort order: "newest", "oldest", "popular", or "rating" Number of results to return (min: 1, max: 100) Number of results to skip for pagination (min: 0) ### Response ```json theme={null} [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Technical Blog Writer", "prompt": "You are an expert technical writer...", "description": "A prompt for generating high-quality technical blog posts", "use_cases": [ { "title": "Tutorial Creation", "description": "Generate step-by-step technical tutorials" } ], "tags": "writing,technical,blog", "is_free": false, "price_usd": 4.99, "price": 0.012, "category": "content", "status": "approved", "tokenized_on": false, "image_url": "https://example.com/image.jpg", "file_path": null, "links": [ { "name": "Documentation", "url": "https://example.com/docs" } ], "seller_wallet_address": "your-wallet-address", "user_id": "user-123", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ] ``` ### Example Request ```bash cURL theme={null} curl -X POST https://swarms.world/api/query-prompts \ -H "Content-Type: application/json" \ -d '{ "search": "technical writing", "category": "content", "priceFilter": "all", "sortBy": "newest", "limit": 10, "offset": 0 }' ``` ```python Python theme={null} import requests url = "https://swarms.world/api/query-prompts" headers = {"Content-Type": "application/json"} data = { "search": "technical writing", "category": "content", "priceFilter": "all", "sortBy": "newest", "limit": 10, "offset": 0 } response = requests.post(url, json=data, headers=headers) prompts = response.json() for prompt in prompts: print(f"Name: {prompt['name']}") print(f"Price: ${prompt['price_usd']}") print(f"URL: {prompt.get('listing_url', 'N/A')}") print("---") ``` ```javascript JavaScript theme={null} const response = await fetch('https://swarms.world/api/query-prompts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ search: 'technical writing', category: 'content', priceFilter: 'all', sortBy: 'newest', limit: 10, offset: 0 }) }); const prompts = await response.json(); prompts.forEach(prompt => { console.log(`Name: ${prompt.name}`); console.log(`Price: $${prompt.price_usd}`); console.log('---'); }); ``` ### Query Parameters Explained * **search**: Searches in both the prompt name and description fields * **category**: Filters results to only show prompts in the specified category * **priceFilter**: * `'all'`: Shows both free and paid prompts * `'free'`: Shows only prompts where `is_free` is true * `'paid'`: Shows only prompts where `is_free` is false * **sortBy**: * `'newest'`: Sorts by creation date, newest first * `'oldest'`: Sorts by creation date, oldest first * `'popular'`: Sorts by popularity metrics * `'rating'`: Sorts by average user rating *** ## Rate Limiting All prompt management endpoints are subject to rate limiting: * **Daily Limit**: 500 prompts per user per day * **Reset Time**: Midnight UTC * **Free Content Limit**: 500 free prompts per day * **Paid Content Limit**: 500 paid prompts per day When the rate limit is exceeded, you'll receive a `429` error response: ```json theme={null} { "error": "Daily limit exceeded", "message": "Daily limit reached: 500 prompts per day. Resets at midnight.", "currentUsage": { "paidPrompts": 500, "paidAgents": 0, "freeContent": 0, "date": "2024-01-01" }, "limits": { "paidPrompts": 500, "paidAgents": 500, "freeContent": 500 }, "resetTime": "2024-01-02T00:00:00.000Z" } ``` *** ## Error Responses The API returns standard HTTP status codes: * `200`: Success * `400`: Bad Request (validation errors) * `401`: Unauthorized (authentication required) * `403`: Forbidden (content validation failed) * `404`: Not Found * `429`: Too Many Requests (rate limit exceeded) * `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 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_url` or links * Missing `price_usd` when `is_free` is false * Invalid use case format (missing title or description) * Duplicate content: response includes `existingId` with the existing prompt ID * Tokenization: when `tokenized_on` is true, missing or invalid `ticker`, `creator_wallet`, or `private_key` *** ## Content Validation All prompts undergo automatic validation for: * **Duplicate Detection**: 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 Prompts that fail validation will receive a `403 Forbidden` or `400 Bad Request` response with details about the validation failure. ### Validation Response Example (duplicate) ```json theme={null} { "error": "Content validation failed", "message": "This prompt appears to be a duplicate of an existing prompt", "details": "...", "existingId": "uuid-of-existing-prompt", "status_code": 400 } ``` *** ## Price Conversion When you submit a prompt with `price_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 This conversion happens automatically and is transparent to the user. *** ## Database Schema Prompts are stored with the following key fields: ```typescript theme={null} interface Prompt { id: string; // UUID user_id: string; // User who created the prompt name: string; // Prompt name prompt: string; // Prompt content description?: string; // Optional description use_cases: UseCase[]; // Array of use cases tags?: string; // Comma-separated tags is_free: boolean; // Free or paid price_usd?: number; // Price in USD price?: number; // Price in SOL category?: string; // Category status: string; // pending/approved/rejected tokenized_on?: boolean; // Blockchain tokenization image_url?: string; // Image URL file_path?: string; // Associated file path links?: Link[]; // Related links seller_wallet_address?: string; // Payment wallet created_at: string; // Creation timestamp updated_at: string; // Last update timestamp } ``` *** ## Using Marketplace Prompts with Agents Once you have a prompt in the marketplace, you can use it with any agent by specifying the `marketplace_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 1. Query the marketplace to find a suitable prompt using the [Query Prompts](#query-prompts) endpoint 2. Copy the prompt's `id` from the response 3. Use the `marketplace_prompt_id` field in your agent configuration 4. The system automatically retrieves and applies the prompt to your agent ### Example: Using a Marketplace Prompt ```python Python theme={null} import requests # Step 1: Find a suitable prompt query_response = requests.post( "https://swarms.world/api/query-prompts", headers={"Content-Type": "application/json"}, json={ "search": "technical writing", "category": "content", "limit": 1 } ) prompts = query_response.json() prompt_id = prompts[0]["id"] # Get the prompt ID # Step 2: Use the prompt with an agent agent_response = requests.post( "https://api.swarms.world/v1/agent/completions", headers={ "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" }, json={ "agent_config": { "agent_name": "marketplace-agent", "model_name": "gpt-4.1-mini", "marketplace_prompt_id": prompt_id, "max_loops": 1 }, "task": "Write a blog post about Python async/await" } ) print(agent_response.json()) ``` ```javascript JavaScript theme={null} // Step 1: Find a suitable prompt const queryResponse = await fetch('https://swarms.world/api/query-prompts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ search: 'technical writing', category: 'content', limit: 1 }) }); const prompts = await queryResponse.json(); const promptId = prompts[0].id; // Step 2: Use the prompt with an agent const agentResponse = await fetch('https://api.swarms.world/v1/agent/completions', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_config: { agent_name: 'marketplace-agent', model_name: 'gpt-4.1-mini', marketplace_prompt_id: promptId, max_loops: 1 }, task: 'Write a blog post about Python async/await' }) }); const result = await agentResponse.json(); console.log(result); ``` ```bash cURL theme={null} # Step 1: Find a suitable prompt PROMPT_ID=$(curl -X POST https://swarms.world/api/query-prompts \ -H "Content-Type: application/json" \ -d '{"search": "technical writing", "category": "content", "limit": 1}' \ | jq -r '.[0].id') # Step 2: Use the prompt with an agent curl -X POST https://api.swarms.world/v1/agent/completions \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"agent_config\": { \"agent_name\": \"marketplace-agent\", \"model_name\": \"gpt-4.1-mini\", \"marketplace_prompt_id\": \"$PROMPT_ID\", \"max_loops\": 1 }, \"task\": \"Write a blog post about Python async/await\" }" ``` ### Direct Usage with Known Prompt ID If you already know the prompt ID, you can use it directly: ```python theme={null} import requests response = requests.post( "https://api.swarms.world/v1/agent/completions", headers={ "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" }, json={ "agent_config": { "agent_name": "marketplace-agent", "model_name": "gpt-4.1-mini", "marketplace_prompt_id": "92a11cf5-ac78-41b7-a4a6-005a92670462", "max_loops": 1 }, "task": "Your task here" } ) print(response.json()) ``` ### Important Notes * When `marketplace_prompt_id` is provided, it takes precedence over the `system_prompt` field * 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](/docs/documentation/capabilities/agent)