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

Request Body

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

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_url": "https://swarms.world/prompt/550e8400-e29b-41d4-a716-446655440000"
}

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

{
  "error": "Validation error",
  "message": "Prompt content must be at least 5 characters long",
  "code": "VALIDATION_ERROR"
}

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
Missing seller_wallet_address for paid prompts
Invalid use case format (missing title or description)

Content Validation

All prompts undergo automatic validation for:

Duplicate Detection: Checks if the same prompt content already exists for the user
Quality Assessment: Evaluates prompt clarity and completeness
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 response with details about the validation failure.

Validation Response Example

{
  "error": "Content validation failed",
  "message": "This prompt appears to be a duplicate of an existing prompt",
  "code": "DUPLICATE_CONTENT"
}

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
}

​Authentication

​Base URL

​Create Prompt

​Endpoint

​Request Body

​Response

​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

​Price Conversion

​Database Schema

Authentication

Base URL

Create Prompt

Endpoint

Request Body

Response

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

Price Conversion

Database Schema