API Introduction

Get started with the SuperBox REST API

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

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