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 -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

{
  "status": "success",
  "message": "Optional human-readable message",
  // Endpoint-specific payload (e.g., "server", "servers", "total")
}

​
Error Response

{
  "status": "error",
  "detail": "Human-readable error message"
}

​
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
​
500 Internal Server Error
error
Server error - please contact support
​
Authorization
string
Bearer token for authenticated requests. Format: Bearer <firebase_id_token>

​
Filtering

The servers list endpoint supports filtering by author: 
# Filter by author
curl "https://api.superbox.ai/api/v1/servers?author=areeb"

​
Versioning

The API uses URL versioning:
  • Current Version: v1
  • Base Path: /api/v1

​
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

​
Support & Resources

Support

Contact our support team

GitHub

View source and report issues

​
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