Skip to main content

​
Welcome to SuperBox API

The SuperBox API is a REST API that allows you to programmatically interact with the SuperBox platform. Create, update, delete, and execute MCP servers using simple HTTP requests.

Base URL

https://api.superbox.ai/api/v1

​
Key Features

RESTful Design

Clean, predictable URLs and standard HTTP methods

JSON Responses

All responses are in JSON format with consistent structure

Bearer Auth

Secure authentication using Firebase JWT tokens

Comprehensive Errors

Detailed error messages with status codes and descriptions

​
API Endpoints Overview

​
Servers Management

​
GET /servers
endpoint
List all available MCP servers with optional filtering
​
GET /servers/:name
endpoint
Get detailed information about a specific server
​
POST /servers
endpoint
required
Create and deploy a new MCP server (requires authentication)
​
PUT /servers/:name
endpoint
required
Update an existing server’s metadata (requires authentication)
​
DELETE /servers/:name
endpoint
required
Remove a server from the registry (requires authentication)

​
Making Your First Request

cURL
curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type": "application/json"

​
Response Format

All API responses follow a consistent structure:

​
Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1"
  }
}

​
Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error context
    }
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:
​
200 OK
success
Request succeeded
​
201 Created
success
Resource successfully created
​
400 Bad Request
error
Invalid request parameters or body
​
401 Unauthorized
error
Missing or invalid authentication token
​
403 Forbidden
error
Authenticated but not authorized to access resource
​
404 Not Found
error
Resource not found
​
409 Conflict
error
Resource already exists or conflicting state
​
429 Too Many Requests
error
Rate limit exceeded
​
500 Internal Server Error
error
Server error - please contact support

​
Rate Limiting

The API implements rate limiting to ensure fair usage:

Authenticated Requests

  • 1000 requests/hour per user
  • 50 requests/minute per user

Unauthenticated Requests

  • 100 requests/hour per IP
  • 10 requests/minute per IP

​
Rate Limit Headers

Every API response includes rate limit information: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1702123456
​
X-RateLimit-Limit
integer
Maximum number of requests allowed per hour
​
X-RateLimit-Remaining
integer
Number of requests remaining in the current window
​
X-RateLimit-Reset
integer
Unix timestamp when the rate limit resets

​
Pagination

List endpoints support pagination using query parameters:
​
page
integer
default:"1"
Page number (1-indexed)
​
limit
integer
default:"20"
Number of items per page (max: 100)

​
Example

curl "https://api.superbox.ai/api/v1/servers?page=2&limit=50"

​
Pagination Response

{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "page": 2,
      "limit": 50,
      "total": 247,
      "totalPages": 5,
      "hasNext": true,
      "hasPrev": true
    }
  }
}

​
Filtering & Sorting

​
Filter by Language

curl "https://api.superbox.ai/api/v1/servers?lang=python"

​
Filter by Author

curl "https://api.superbox.ai/api/v1/servers?author=areeb"

​
Filter by Price

# Free servers only
curl "https://api.superbox.ai/api/v1/servers?pricing=free"

# Paid servers only
curl "https://api.superbox.ai/api/v1/servers?pricing=paid"

​
Sort Results

# Sort by creation date (newest first)
curl "https://api.superbox.ai/api/v1/servers?sort=-created_at"

# Sort by name (A-Z)
curl "https://api.superbox.ai/api/v1/servers?sort=name"

# Multiple sort fields
curl "https://api.superbox.ai/api/v1/servers?sort=-downloads,name"
Use - prefix for descending order (e.g., -created_at)

​
Versioning

The API uses URL versioning:
  • Current Version: v1
  • Base Path: /api/v1
Future versions will be released as /api/v2, /api/v3, etc. We maintain backward compatibility for at least 12 months after a new version release.

​
CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based requests: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

​
Webhooks

SuperBox can send webhook notifications for various events:
Triggered when a new server is published
Triggered when a server’s metadata is updated
Triggered when a server is removed
Triggered when a server execution finishes
Triggered when security scanning completes
Configure webhooks in your account settings.

​
SDKs & Libraries

Python SDK

pip install superbox-sdk

Node.js SDK

npm install @superbox/sdk

Go SDK

go get github.com/superbox/sdk-go

​
Support & Resources

API Status

Check API uptime and performance

Postman Collection

Import our Postman collection

OpenAPI Spec

Download OpenAPI 3.0 specification

Support

Contact our support team

​
Next Steps

Authentication

Learn how to authenticate your requests

Error Handling

Understand error codes and handling

List Servers

Get started with the Servers API

Create Server

Deploy your first MCP server