> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Card title="Base URL" icon="link">
  ```
  https://api.superbox.ai/api/v1
  ```
</Card>

## Key Features

<CardGroup cols={2}>
  <Card title="RESTful Design" icon="code">
    Clean, predictable URLs and standard HTTP methods
  </Card>

  <Card title="JSON Responses" icon="brackets-curly">
    All responses are in JSON format with consistent structure
  </Card>

  <Card title="Bearer Auth" icon="key">
    Secure authentication using Firebase JWT tokens
  </Card>

  <Card title="Comprehensive Errors" icon="triangle-exclamation">
    Detailed error messages with status codes and descriptions
  </Card>
</CardGroup>

## API Endpoints Overview

### Servers Management

<ResponseField name="GET /servers" type="endpoint">
  List all available MCP servers with optional filtering
</ResponseField>

<ResponseField name="GET /servers/:name" type="endpoint">
  Get detailed information about a specific server
</ResponseField>

<ResponseField name="POST /servers" type="endpoint" required>
  Create and deploy a new MCP server (requires authentication)
</ResponseField>

<ResponseField name="PUT /servers/:name" type="endpoint" required>
  Update an existing server's metadata (requires authentication)
</ResponseField>

<ResponseField name="DELETE /servers/:name" type="endpoint" required>
  Remove a server from the registry (requires authentication)
</ResponseField>

## Making Your First Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.superbox.ai/api/v1/servers" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.superbox.ai/api/v1/servers", {
    method: "GET",
    headers: {
   Authorization: "Bearer YOUR_API_TOKEN",
   "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.superbox.ai/api/v1/servers"
  headers = {
   "Authorization": "Bearer YOUR_API_TOKEN",
   "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response Format

All API responses follow a consistent structure:

### Success Response

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

### Error Response

```json theme={null}
{
  "status": "error",
  "detail": "Human-readable error message"
}
```

## HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

<ResponseField name="200 OK" type="success">
  Request succeeded
</ResponseField>

<ResponseField name="201 Created" type="success">
  Resource successfully created
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Invalid request parameters or body
</ResponseField>

<ResponseField name="401 Unauthorized" type="error">
  Missing or invalid authentication token
</ResponseField>

<ResponseField name="403 Forbidden" type="error">
  Authenticated but not authorized to access resource
</ResponseField>

<ResponseField name="404 Not Found" type="error">
  Resource not found
</ResponseField>

<ResponseField name="409 Conflict" type="error">
  Resource already exists or conflicting state
</ResponseField>

<ResponseField name="500 Internal Server Error" type="error">
  Server error - please contact support
</ResponseField>

<ParamField header="Authorization" type="string">
  Bearer token for authenticated requests. **Format:** `Bearer <firebase_id_token>`
</ParamField>

## Filtering

The servers list endpoint supports filtering by author:

```bash theme={null}
# 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:

```http theme={null}
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

## Support & Resources

<CardGroup cols={2}>
  <Card title="Support" icon="life-ring" href="mailto:hi@areeb.dev">
    Contact our support team
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/1mindlabs/superbox">
    View source and report issues
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate your requests
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api/errors">
    Understand error codes and handling
  </Card>

  <Card title="List Servers" icon="list" href="/api/servers/list">
    Get started with the Servers API
  </Card>

  <Card title="Create Server" icon="plus" href="/api/servers/create">
    Deploy your first MCP server
  </Card>
</CardGroup>