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

This quickstart sends one request to POST /v1/decision/completions that asks three questions about a support ticket, then reads the answers and the cost. Every request and response on this page was run against production.

1. Get an API Key

Create a key at swarms.world/platform/api-keys and export it. Your account needs more than $1.00 of purchased credit.

export SWARMS_API_KEY="your-api-key-here"

2. Ask One Question

A noul question returns the probability that a statement is true. model_name defaults to jev-latest, so it can be left out.

cURL
Python

curl -X POST "https://api.swarms.world/v1/decision/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "I was charged twice for my order. Please refund one.",
    "questions": {
      "billing": {"type": "noul", "instructions": "Is this about billing?"}
    }
  }'

import os

import requests

response = requests.post(
    "https://api.swarms.world/v1/decision/completions",
    headers={"x-api-key": os.environ["SWARMS_API_KEY"]},
    json={
        "state": "I was charged twice for my order. Please refund one.",
        "questions": {
            "billing": {"type": "noul", "instructions": "Is this about billing?"},
        },
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["answers"]["billing"]["noul"])

{"billing": {"type": "noul", "noul": 0.98}}

noul is 0.98: almost certainly a billing ticket. Branch on it with a threshold, such as > 0.5.

3. Ask Three Kinds of Question at Once

Add a choice question to pick a team and a score question to rate severity. All three are answered in one request, and the ticket’s tokens are billed once.

import os

import requests

response = requests.post(
    "https://api.swarms.world/v1/decision/completions",
    headers={"x-api-key": os.environ["SWARMS_API_KEY"]},
    json={
        "model_name": "jev-latest",
        "state": "Checkout has been failing for every customer since 9am. We are losing orders.",
        "questions": {
            "is_urgent": {"type": "noul", "instructions": "Is this urgent?"},
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {
                    "payments": "Checkout, billing, refunds",
                    "infra": "Outages, latency, servers",
                    "support": None,
                },
            },
            "severity": {
                "type": "score",
                "instructions": "How severe is the impact?",
                "criteria": ["No impact", "Minor", "Major", "Critical"],
            },
        },
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
answers = result["answers"]

print("Urgent:", answers["is_urgent"]["noul"])
print("Team:", answers["team"]["choice"], "confidence", answers["team"]["confidence"])
print("Severity:", answers["severity"]["legend"][str(round(answers["severity"]["score"]))])
print("Answered by:", result["model"])
print("Cost:", result["usage"]["total_cost"])

Urgent: 0.97
Team: payments confidence 0.88
Severity: Critical
Answered by: jev-1.14.0
Cost: 1.89819e-05

choice is the most likely option, and probabilities holds all of them: payments 0.92, infra 0.07, support 0.01.
score is 2.99 on levels numbered from 0, so legend["3"] names it: Critical.
model is the version that answered the jev-latest alias.

4. Check the Cost

The request used 393 input tokens at $0.0483 per 1M, and output tokens are free: 393 × $0.0483 / 1,000,000 = $0.0000190, the usage.total_cost above. The same charge is in the x-swarms-total-cost response header. At that rate 10,000 tickets cost about $0.19. Prices come from GET /v1/decision/models.

5. Already Using TypeSafe?

POST /v1/systemone takes and returns the TypeSafe API’s exact format, so point TypeSafe code at https://api.swarms.world with your Swarms key:

curl -X POST "https://api.swarms.world/v1/systemone" \
  -H "Authorization: Bearer $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "jev-latest", "state": "I was charged twice.", "questions": {"billing": {"type": "noul", "instructions": "Is this about billing?"}}}'

Next Steps

Decision Models and SystemOne Reference: every field, answer type, header, price and error
Decision Model Completion: the three-question request in cURL and Python, answer by answer
Gate and Judge an Agent: skip agent calls you don’t need, and grade the ones you run
Pick a Swarm and the Best Draft: choose a swarm_type and the winning output
SystemOne: Use the TypeSafe Format: Bearer auth, headers and the TypeSafe model list

Getting Started

Clients

Agent Completions

Decision Models

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Decision Models Quickstart

1. Get an API Key

2. Ask One Question

3. Ask Three Kinds of Question at Once

4. Check the Cost

5. Already Using TypeSafe?

Next Steps

​1. Get an API Key

​2. Ask One Question

​3. Ask Three Kinds of Question at Once

​4. Check the Cost

​5. Already Using TypeSafe?

​Next Steps

1. Get an API Key

2. Ask One Question

3. Ask Three Kinds of Question at Once

4. Check the Cost

5. Already Using TypeSafe?

Next Steps