Skip to main content
DELETE
/
servers
/
:name
Delete Server
curl --request DELETE \
  --url https://api.example.com/servers/:name
{
  "success": true,
  "data": {
    "name": "my-test-server",
    "deleted_at": "2025-12-09T10:30:00Z",
    "activeUsers": 5,
    "backupId": "backup_abc123def456",
    "message": "Server deleted successfully. Backup available for 30 days for recovery."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

Endpoint

Authentication

This endpoint requires authentication. You must be the server owner.
Only the server owner can delete a server. This action is irreversible.

Path Parameters

name
string
required
Unique server identifier to delete Example: weather-mcp, my-test-server

Query Parameters

confirm
boolean
default:"false"
Confirmation flag to prevent accidental deletions Must be: true to proceed with deletion
force
boolean
default:"false"
Force deletion even if server has active users
Use with caution. This may disrupt users actively using your server.

Response

success
boolean
Indicates if deletion was successful
data
object
Deletion confirmation details

Examples

cURL
# Basic deletion (requires confirm=true)
curl -X DELETE "https://api.superbox.ai/api/v1/servers/my-test-server?confirm=true" \
  -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

# Force deletion with active users

curl -X DELETE "https://api.superbox.ai/api/v1/servers/my-server?confirm=true&force=true" \
 -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

Response Examples

{
  "success": true,
  "data": {
    "name": "my-test-server",
    "deleted_at": "2025-12-09T10:30:00Z",
    "activeUsers": 5,
    "backupId": "backup_abc123def456",
    "message": "Server deleted successfully. Backup available for 30 days for recovery."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

Deletion Process

When you delete a server, SuperBox performs these steps:
1

Validation

  • Verify authentication and ownership - Check for confirmation flag - Check for active users (unless force=true)
2

Backup Creation

  • Create backup of server metadata - Store backup for 30-day recovery period - Generate unique backup ID
3

Lambda Cleanup

  • Stop Lambda function - Delete function configuration - Remove ECR container images
4

Registry Update

  • Remove from S3 registry - Update search indexes - Clear cached data
5

User Notification

  • Notify active users (if any) - Send confirmation email to owner - Update analytics

What Gets Deleted

  • Server listing in registry - Lambda function and containers - Public API access - Search index entries - CDN cached data

Before You Delete

async function checkActiveUsers(serverName) {
  const response = await fetch(
    `https://api.superbox.ai/api/v1/servers/${serverName}/stats`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.SUPERBOX_API_TOKEN}`
      }
    }
  );
  
  const stats = await response.json();
  console.log(`Active users: ${stats.data.activeUsers}`);
  console.log(`Daily executions: ${stats.data.dailyExecutions}`);
  
  if (stats.data.activeUsers > 0) {
    console.warn('⚠ Server has active users!');
  }
}
def export_server_data(server_name):
    """Export all server data before deletion"""
    
    # Get server details
    url = f"https://api.superbox.ai/api/v1/servers/{server_name}"
    headers = {'Authorization': f'Bearer {os.getenv("SUPERBOX_API_TOKEN")}'}
    
    response = requests.get(url, headers=headers)
    server_data = response.json()['data']
    
    # Save to file
    import json
    with open(f'{server_name}_backup.json', 'w') as f:
        json.dump(server_data, f, indent=2)
    
    print(f"✓ Data exported to {server_name}_backup.json")
    
    # Get analytics
    analytics_url = f"{url}/analytics"
    analytics = requests.get(analytics_url, headers=headers).json()
    
    with open(f'{server_name}_analytics.json', 'w') as f:
        json.dump(analytics['data'], f, indent=2)
    
    print(f"✓ Analytics exported to {server_name}_analytics.json")
Consider notifying your users before deletion:
  • Post announcement on your homepage
  • Email active users (if you have their contacts)
  • Update README with deprecation notice
  • Suggest alternative servers
// Update description before deletion
await fetch(url, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    description: 'DEPRECATED - This server will be deleted on 2025-12-20. Please migrate to alternative-server.'
  })
});
Instead of deleting, you can deprecate:
// Mark as deprecated
await fetch(url, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    metadata: {
      deprecated: true,
      deprecation_date: '2025-12-09',
      alternative: 'new-improved-server'
    }
  })
});
Deprecation allows users to migrate gradually

Common Deletion Scenarios

Scenario: Deleting a test/development server
# Quick deletion (no active users expected)
curl -X DELETE \
  "https://api.superbox.ai/api/v1/servers/test-server?confirm=true" \
  -H "Authorization: Bearer $TOKEN"
Safe to delete immediately

Recovery Process

If you deleted by mistake, you can recover within 30 days:
1

Contact Support

Email support@superbox.ai with: - Server name - Backup ID (from deletion response) - Reason for recovery
2

Verification

Support will verify: - Your ownership - Backup existence - Recovery eligibility
3

Restoration

If approved: - Server metadata restored - Lambda function redeployed - Registry updated - Takes 15-30 minutes
4

Confirmation

You’ll receive: - Restoration confirmation email - Updated server URL - Post-recovery checklist
Recovery is only available for 30 days after deletion

Best Practices

Export First

Always export server data and analytics before deletion

Notify Users

Give users advance notice (7-30 days recommended)

Save Backup ID

Store the backup ID in case you need to recover

Check Dependencies

Ensure no other systems depend on your server

Consider Alternatives

Deprecation or making private instead of deletion

Double Confirmation

Use UI confirmation dialogs to prevent accidents

Alternative Actions

Instead of deletion, consider:
// Make server private (coming soon)
await updateServer(name, {
  visibility: 'private'
});
// Transfer to another user (coming soon)
await transferServer(name, {
  newOwner: 'user@example.com'
});
// Mark as archived
await updateServer(name, {
  metadata: {
    archived: true,
    archived_date: new Date().toISOString()
  }
});

Security Considerations

Important Security Notes: - Deletion does not remove git history - Public forks of your repository remain accessible - User-generated content (reviews) is anonymized but retained - Transaction data is retained for compliance If your server contained sensitive information: 1. Delete from source repository 2. Rotate any exposed credentials 3. Contact support for additional cleanup
Think carefully before deleting. Deprecation is often a better choice!