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

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 <your-api-key>
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)

name

string

required

The name of the prompt (minimum 2 characters)

prompt

string

required

The prompt content (minimum 5 characters)

description

string

A detailed description of what the prompt does and when to use it

useCases

array

required

An array of use cases demonstrating the prompt’s applications

[
  {
    "title": "Content Generation",
    "description": "Generate blog posts and articles"
  }
]

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)

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

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

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:

string

required

The unique identifier of the prompt to update

Response

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

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

Query Prompts

Search and filter prompts in the marketplace.

Endpoint

POST /api/query-prompts

Request Body

string

Search query to match against prompt names and descriptions (max 100 characters)

Response

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

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

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:

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

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

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

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

Query the marketplace to find a suitable prompt using the Query Prompts endpoint
Copy the prompt’s id from the response
Use the marketplace_prompt_id field in your agent configuration
The system automatically retrieves and applies the prompt to your agent

Example: Using a Marketplace Prompt

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-4o-mini",
            "marketplace_prompt_id": prompt_id,
            "max_loops": 1
        },
        "task": "Write a blog post about Python async/await"
    }
)

print(agent_response.json())

Direct Usage with Known Prompt ID

If you already know the prompt ID, you can use it directly:

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-4o-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

Platform

Launchpad

API

Resources

​Authentication

​Base URL

​Create Prompt

​Endpoint

​Input schema (Add Prompt)

​Request Body (detailed)

​Validation rules

​Success response (200)

​Output schema (Add Prompt — success)

​Error responses (Add Prompt)

​Error output schema (common fields)

​Example Request

​Update Prompt

​Endpoint

​Request Body

​Response

​Example Request

​Query Prompts

​Endpoint

​Request Body

​Response

​Example Request

​Query Parameters Explained

​Rate Limiting

​Error Responses

​Example Error Response

​Common Validation Errors

​Content Validation

​Validation Response Example (duplicate)

​Price Conversion

​Database Schema

​Using Marketplace Prompts with Agents

​How It Works

​Example: Using a Marketplace Prompt

​Direct Usage with Known Prompt ID

​Important Notes

Authentication

Base URL

Create Prompt

Endpoint

Input schema (Add Prompt)

Request Body (detailed)

Validation rules

Success response (200)

Output schema (Add Prompt — success)

Error responses (Add Prompt)

Error output schema (common fields)

Example Request

Update Prompt

Endpoint

Request Body

Response

Example Request

Query Prompts

Endpoint

Request Body

Response

Example Request

Query Parameters Explained

Rate Limiting

Error Responses

Example Error Response

Common Validation Errors

Content Validation

Validation Response Example (duplicate)

Price Conversion

Database Schema

Using Marketplace Prompts with Agents

How It Works

Example: Using a Marketplace Prompt

Direct Usage with Known Prompt ID

Important Notes