Skip to main content
Publish a Bundle — a curated collection of marketplace agents, prompts, and custom inline prompts — straight from your code or CI pipeline, in 3 easy steps:
  1. Authenticate: Secure your request with an API key.
  2. Publish: POST your bundle’s name, description, and items.
  3. Get your listing: Instantly receive the public bundle URL.

​
Step 1: Authentication

Send your API key in the Authorization header as a Bearer token: 
Authorization: Bearer <your-api-key>
Get your API key from swarms.world/platform/api-keys.

​
Base URL

https://swarms.world

​
Step 2: Publish a Bundle

​
Endpoint

POST /api/v1/publish/bundle

​
Input schema

ParameterTypeRequiredDescription
namestringYesBundle display name (2–200 characters). Names containing test or example are rejected.
descriptionstringNoWhat the bundle is for (max 10,000 characters)
itemsarrayYes1–50 bundle items — see item shape below
tagsstringNoComma-separated tags (max 500 characters)
image_urlstringNoPublic cover image URL
image_base64stringNoBase64-encoded cover image (alternative to image_url; may include a data:image/...;base64, prefix)
linksarrayNoSupporting links; each { "name": string, "url": string } (max 20)
business_modelstringNoOptional business model label

​
Item shape

Each entry in items is one of two kinds:
KindFieldsDescription
Marketplace referenceurlLink to an existing agent or prompt listing, e.g. https://swarms.world/agent/<id>. The bundle page enriches it with the live name and description.
Custom inline promptname (required), description, contentA prompt bundled directly without publishing it as a standalone listing
Every item needs either a url or a name. A bundle must contain at least one item. Bundles are free products — free to publish and free to access.

​
Example request

curl -X POST https://swarms.world/api/v1/publish/bundle \
  -H "Authorization: Bearer $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial Analysis Starter Kit",
    "description": "Everything you need to analyze equities: a research agent, a summarizer prompt, and my custom risk checklist.",
    "tags": "finance,research,analysis",
    "items": [
      { "url": "https://swarms.world/agent/2d5bd840-2830-4b2f-9709-02cab69a442b" },
      { "url": "https://swarms.world/prompt/e0686b13-7f41-44f4-adc4-6c1f468793fb" },
      {
        "name": "Risk Checklist",
        "description": "Pre-trade risk review",
        "content": "Before recommending any position, verify: 1) liquidity..."
      }
    ],
    "links": [
      { "name": "GitHub", "url": "https://github.com/your-org/finance-kit" }
    ]
  }'

import os
import requests

response = requests.post(
    "https://swarms.world/api/v1/publish/bundle",
    headers={
        "Authorization": f"Bearer {os.environ['SWARMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Financial Analysis Starter Kit",
        "description": "Everything you need to analyze equities.",
        "tags": "finance,research,analysis",
        "items": [
            {"url": "https://swarms.world/agent/2d5bd840-2830-4b2f-9709-02cab69a442b"},
            {
                "name": "Risk Checklist",
                "description": "Pre-trade risk review",
                "content": "Before recommending any position, verify: ...",
            },
        ],
    },
    timeout=30,
)
print(response.json())

const response = await fetch("https://swarms.world/api/v1/publish/bundle", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SWARMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Financial Analysis Starter Kit",
    description: "Everything you need to analyze equities.",
    tags: "finance,research,analysis",
    items: [
      { url: "https://swarms.world/agent/2d5bd840-2830-4b2f-9709-02cab69a442b" },
      {
        name: "Risk Checklist",
        description: "Pre-trade risk review",
        content: "Before recommending any position, verify: ...",
      },
    ],
  }),
});
console.log(await response.json());

​
Step 3: Get Your Listing

​
Success response

{
  "success": true,
  "id": "b3f1c2d4-5678-4abc-9def-0123456789ab",
  "listing_url": "https://swarms.world/bundle/b3f1c2d4-5678-4abc-9def-0123456789ab",
  "item_count": 3
}
FieldTypeDescription
successbooleantrue when the bundle was published
idstringThe bundle’s public identifier (UUID)
listing_urlstringPublic marketplace URL of your bundle
item_countnumberNumber of items saved in the bundle

​
Error responses

StatusErrorMeaning
400Validation errorRequest body failed schema validation — see the errors array for details
400Invalid nameName contains a blocked word (test, example)
401Authentication requiredMissing or invalid API key
405Method not allowedOnly POST is accepted
409Duplicate bundleYou already have a bundle with this name — the response includes existing_id and existing_url
429Daily limit exceededMaximum 20 bundles per user per day
500Database error / Internal server errorSomething went wrong on our side — retry later
Rate limit: 20 bundles per user per UTC day. Duplicate names (same user, same bundle name) are rejected with 409 so retried requests never double-publish.

Bundles Overview

What bundles are and how they work on the marketplace

List Your Products

Fetch everything you’ve published, including bundles

Agents API

Publish agents programmatically

API Keys

Create and manage your API keys