Reviews API

https://swarms.world

Authorization: Bearer <your_api_key>

{
  "model_id": "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b",
  "model_type": "agent",
  "rating": 4,
  "comment": "Solid agent for structured data extraction. Handles nested JSON reliably. Occasionally slow on very large payloads but otherwise works great."
}

{
  "success": true,
  "review": {
    "id": "7a3c1d2e-4f5b-6a7c-8d9e-0f1a2b3c4d5e",
    "model_id": "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b",
    "model_type": "agent",
    "rating": 4,
    "comment": "Solid agent for structured data extraction. Handles nested JSON reliably. Occasionally slow on very large payloads but otherwise works great.",
    "created_at": "2026-04-13T09:15:22.413Z"
  }
}

GET /api/reviews?model_id=d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b

{
  "reviews": [
    {
      "id": "7a3c1d2e-4f5b-6a7c-8d9e-0f1a2b3c4d5e",
      "model_id": "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b",
      "model_type": "agent",
      "rating": 4,
      "comment": "Solid agent for structured data extraction. Handles nested JSON reliably.",
      "created_at": "2026-04-13T09:15:22.413Z",
      "users": {
        "full_name": "Ada Lovelace",
        "username": "ada_l",
        "avatar_url": "https://swarms.world/avatars/ada_l.jpg"
      }
    },
    {
      "id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "model_id": "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b",
      "model_type": "agent",
      "rating": 5,
      "comment": "Best data agent I have used. Fully reliable, great documentation.",
      "created_at": "2026-04-10T14:30:00.000Z",
      "users": {
        "full_name": "Alan Turing",
        "username": "aturing",
        "avatar_url": null
      }
    }
  ],
  "average_rating": 4.5,
  "total": 2
}

interface Review {
  id: string;           // UUID — unique review identifier
  model_id: string;     // ID of the reviewed agent, prompt, or tool
  model_type: string;   // "agent" | "prompt" | "tool"
  rating: number;       // Integer 1–5
  comment: string;      // Reviewer's written comment (trimmed)
  created_at: string;   // ISO 8601 UTC timestamp
}

interface ReviewWithUser extends Review {
  users: {
    full_name: string | null;
    username: string | null;
    avatar_url: string | null;
  } | null;
}

interface ReviewsResponse {
  reviews: ReviewWithUser[];
  average_rating: number | null;  // null when total === 0
  total: number;
}

interface SubmitReviewResponse {
  success: true;
  review: Review;
}

interface ErrorResponse {
  error: string;
}

{ "error": "<human-readable message>" }

curl -X POST https://swarms.world/api/reviews \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b",
    "model_type": "agent",
    "rating": 5,
    "comment": "Excellent performance on multi-step reasoning tasks. Highly recommended."
  }'

curl "https://swarms.world/api/reviews?model_id=d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b"

import requests

API_KEY = "sk-your-api-key-here"
BASE_URL = "https://swarms.world"


def submit_review(model_id: str, model_type: str, rating: int, comment: str) -> dict:
    """
    Submit a 1–5 star review for an agent, prompt, or tool.

    Args:
        model_id:   Unique ID of the item (from its listing URL).
        model_type: One of "agent", "prompt", or "tool".
        rating:     Integer from 1 (Poor) to 5 (Excellent).
        comment:    Written review, minimum 2 characters.

    Returns:
        dict with keys "success" (bool) and "review" (dict) on success.

    Raises:
        requests.HTTPError on 4xx / 5xx responses.
    """
    response = requests.post(
        f"{BASE_URL}/api/reviews",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model_id": model_id,
            "model_type": model_type,
            "rating": rating,
            "comment": comment,
        },
    )
    response.raise_for_status()
    return response.json()


def get_reviews(model_id: str) -> dict:
    """
    Fetch all reviews for a given item.

    Args:
        model_id: Unique ID of the agent, prompt, or tool.

    Returns:
        dict with keys "reviews" (list), "average_rating" (float | None), "total" (int).
    """
    response = requests.get(
        f"{BASE_URL}/api/reviews",
        params={"model_id": model_id},
    )
    response.raise_for_status()
    return response.json()


# ── Example usage ────────────────────────────────────────────────────────────

MODEL_ID = "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b"

# Submit
result = submit_review(
    model_id=MODEL_ID,
    model_type="agent",
    rating=4,
    comment="Reliable and well-documented. Handles edge cases cleanly.",
)
print("Submitted:", result["review"]["id"])

# Read back
data = get_reviews(MODEL_ID)
print(f"Average: {data['average_rating']} across {data['total']} review(s)")
for review in data["reviews"]:
    user = review.get("users") or {}
    print(f"  ★{review['rating']}  {user.get('username', 'unknown')}: {review['comment'][:60]}")

import requests

def safe_submit_review(model_id, model_type, rating, comment):
    try:
        return submit_review(model_id, model_type, rating, comment)
    except requests.HTTPError as exc:
        if exc.response.status_code == 409:
            print("Already reviewed this item — skipping.")
            return None
        raise

const API_KEY = process.env.SWARMS_API_KEY!;
const BASE_URL = "https://swarms.world";

interface SubmitReviewPayload {
  model_id: string;
  model_type: "agent" | "prompt" | "tool";
  rating: 1 | 2 | 3 | 4 | 5;
  comment: string;
}

interface Review {
  id: string;
  model_id: string;
  model_type: string;
  rating: number;
  comment: string;
  created_at: string;
}

interface ReviewWithUser extends Review {
  users: {
    full_name: string | null;
    username: string | null;
    avatar_url: string | null;
  } | null;
}

interface SubmitReviewResponse {
  success: true;
  review: Review;
}

interface GetReviewsResponse {
  reviews: ReviewWithUser[];
  average_rating: number | null;
  total: number;
}

/** Submit a rating and comment for an agent, prompt, or tool. */
async function submitReview(payload: SubmitReviewPayload): Promise<SubmitReviewResponse> {
  const res = await fetch(`${BASE_URL}/api/reviews`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} — ${body.error ?? "Unknown error"}`);
  }

  return res.json() as Promise<SubmitReviewResponse>;
}

/** Fetch all reviews for a given item. No API key required. */
async function getReviews(modelId: string): Promise<GetReviewsResponse> {
  const url = new URL(`${BASE_URL}/api/reviews`);
  url.searchParams.set("model_id", modelId);

  const res = await fetch(url.toString());

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} — ${body.error ?? "Unknown error"}`);
  }

  return res.json() as Promise<GetReviewsResponse>;
}

// ── Example usage ─────────────────────────────────────────────────────────

const MODEL_ID = "d4f2a1b3-9c8e-4f1d-b2a7-3e5c6d8f0a2b";

// Submit
const { review } = await submitReview({
  model_id: MODEL_ID,
  model_type: "agent",
  rating: 5,
  comment: "Best tool in the marketplace for document parsing.",
});
console.log("Saved review ID:", review.id);

// Read back
const { reviews, average_rating, total } = await getReviews(MODEL_ID);
console.log(`${total} review(s), average ${average_rating ?? "N/A"} stars`);
reviews.forEach((r) => {
  console.log(`  ★${r.rating}  ${r.users?.username ?? "unknown"}: ${r.comment}`);
});

async function submitReviewSafe(payload: SubmitReviewPayload) {
  const res = await fetch(`${BASE_URL}/api/reviews`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (res.status === 409) {
    console.warn("Already reviewed this item — skipping.");
    return null;
  }

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} — ${body.error ?? "Unknown error"}`);
  }

  return res.json() as Promise<SubmitReviewResponse>;
}