Berican Labs - Premium Kenyan Web Hosting

1Getting Started

The Berican Labs API allows you to programmatically manage all aspects of your hosting infrastructure. Whether you're building custom dashboards, automating deployments, or integrating with CI/CD pipelines, our REST API provides full control.

🚀 Use the Official SDK:

We recommend using our Node.js SDK for easier integration with TypeScript support, automatic error handling, and typed responses.

npm install @berican/sdk

Quick Start (REST API):

Generate an API key from your Dashboard
Include the key in the Authorization header
Make requests to https://api.bericanlabs.com/v1

2Authentication

All API requests require authentication using Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer brc_live_your_api_key_here

Creating an API Key:

Navigate to Dashboard → API Keys
Click "Create API Key"
Give your key a descriptive name
Set permissions (read, write, delete)
Copy the key immediately (it's only shown once)

Security Best Practices:

Never commit API keys to version control
Never expose keys in client-side code
Use environment variables for key storage
Rotate keys regularly
Use separate keys for different environments
Set minimal required permissions for each key

API Key Types:

brc_live_* - Production API keys
brc_test_* - Test/development API keys

3Base URL & Request Format

All API endpoints use the following base URL:

https://api.bericanlabs.com/v1

Request Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

All requests and responses use JSON format. Make sure to set the Content-Type: application/json header for POST/PUT requests.

4Sites API

Manage your hosted sites programmatically. Create, list, update, delete, and deploy sites via the API.

GET /sites

List all sites in your account

Query Parameters:

page (optional) - Page number (default: 1)
limit (optional) - Results per page (default: 20, max: 100)
type (optional) - Filter by type: "static" or "wordpress"
status (optional) - Filter by status: "ACTIVE", "PROVISIONING", etc.

Example Request:

curl -X GET "https://api.bericanlabs.com/v1/sites?page=1&limit=10" \
  -H "Authorization: Bearer brc_live_your_api_key"

Example Response:

{
  "data": [
    {
      "id": "clx1234567890",
      "name": "my-awesome-site",
      "slug": "my-awesome-site",
      "type": "STATIC",
      "status": "ACTIVE",
      "subdomain": "my-awesome-site",
      "customDomain": null,
      "url": "https://my-awesome-site.bericanlabs.com",
      "repository": "github.com/user/repo",
      "branch": "main",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T12:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

GET /sites/:id

Get detailed information about a specific site

Example Request:

curl -X GET "https://api.bericanlabs.com/v1/sites/clx1234567890" \
  -H "Authorization: Bearer brc_live_your_api_key"

Example Response:

{
  "id": "clx1234567890",
  "name": "my-awesome-site",
  "slug": "my-awesome-site",
  "type": "STATIC",
  "status": "ACTIVE",
  "subdomain": "my-awesome-site",
  "customDomain": "example.com",
  "url": "https://example.com",
  "repository": "github.com/user/repo",
  "branch": "main",
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": "out",
  "serverId": "srv_abc123",
  "domains": [
    {
      "id": "dom_xyz789",
      "domain": "example.com",
      "status": "ACTIVE",
      "sslStatus": "ACTIVE"
    }
  ],
  "server": {
    "id": "srv_abc123",
    "region": "us-east",
    "status": "ACTIVE"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T12:45:00Z"
}

POST /sites

Create a new site

Request Body:

name (required) - Site name
type (required) - "static" or "wordpress"
repository (optional) - Git repository URL
branch (optional) - Git branch (default: "main")
framework (optional) - Framework type
buildCommand (optional) - Build command
outputDirectory (optional) - Output directory

Example Request:

curl -X POST "https://api.bericanlabs.com/v1/sites" \
  -H "Authorization: Bearer brc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-site",
    "type": "static",
    "repository": "github.com/user/repo",
    "branch": "main",
    "framework": "nextjs"
  }'

Example Response:

{
  "id": "clx9876543210",
  "name": "my-new-site",
  "slug": "my-new-site",
  "type": "STATIC",
  "status": "PROVISIONING",
  "subdomain": "my-new-site",
  "url": "https://my-new-site.bericanlabs.com",
  "repository": "github.com/user/repo",
  "branch": "main",
  "createdAt": "2024-01-16T14:20:00Z"
}

DELETE /sites/:id

Delete a site (soft delete)

Example Request:

curl -X DELETE "https://api.bericanlabs.com/v1/sites/clx1234567890" \
  -H "Authorization: Bearer brc_live_your_api_key"

Example Response:

{
  "success": true,
  "message": "Site deleted successfully"
}

5Deployments API

Trigger and manage deployments for your sites.

POST /sites/:id/deploy

Trigger a new deployment

Request Body (optional):

branch (optional) - Override branch to deploy
clearCache (optional) - Clear build cache (default: false)

Example Request:

curl -X POST "https://api.bericanlabs.com/v1/sites/clx1234567890/deploy" \
  -H "Authorization: Bearer brc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "clearCache": false
  }'

Example Response:

{
  "success": true,
  "message": "Deployment started",
  "deployment": {
    "id": "dep_abc123",
    "siteId": "clx1234567890",
    "status": "BUILDING",
    "branch": "main",
    "commit": "a1b2c3d",
    "startedAt": "2024-01-16T15:30:00Z"
  }
}

6Domains API

Manage domains and DNS configuration for your sites.

GET /domains

List all domains in your account

Query Parameters:

page (optional) - Page number (default: 1)
limit (optional) - Results per page (default: 20)

Example Request:

curl -X GET "https://api.bericanlabs.com/v1/domains" \
  -H "Authorization: Bearer brc_live_your_api_key"

Example Response:

{
  "data": [
    {
      "id": "dom_xyz789",
      "domain": "example.com",
      "status": "ACTIVE",
      "sslStatus": "ACTIVE",
      "siteId": "clx1234567890",
      "site": {
        "id": "clx1234567890",
        "name": "my-site",
        "type": "STATIC"
      },
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

POST /domains/check

Check if a domain is available

Request Body:

domain (required) - Domain name to check

Example Request:

curl -X POST "https://api.bericanlabs.com/v1/domains/check" \
  -H "Authorization: Bearer brc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mynewdomain.com"
  }'

Example Response:

{
  "domain": "mynewdomain.com",
  "available": true,
  "exists": false
}

7Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

Success Codes:

200 OK - Request succeeded
201 Created - Resource created successfully

Client Error Codes:

400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded

Server Error Codes:

500 Internal Server Error - Server error
503 Service Unavailable - Service temporarily unavailable

Error Response Format:

{
  "error": "Invalid request parameters",
  "message": "The 'name' field is required",
  "code": "VALIDATION_ERROR"
}

8Rate Limits

To ensure fair usage and system stability, the API enforces rate limits:

60 requests per minute per API key
1,000 requests per hour per API key
10,000 requests per day per API key

Rate Limit Headers:

Every API response includes headers indicating your current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642345678

Rate Limit Exceeded:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before making more requests.

Need higher rate limits? Contact our support team to discuss enterprise plans.

9Permissions

API keys support granular permissions for different resources and operations:

Available Permissions:

Sites:

sites:read - View sites
sites:write - Create and update sites
sites:delete - Delete sites

Domains:

domains:read - View domains
domains:write - Add and configure domains
domains:delete - Remove domains

Deployments:

deployments:read - View deployment history
deployments:write - Trigger deployments

Best Practice: Create separate API keys with minimal required permissions for different use cases. For example, use a read-only key for monitoring dashboards.

10Code Examples

Here are examples of using the API in different programming languages:

JavaScript (Node.js)

const API_KEY = process.env.BERICAN_API_KEY;
const BASE_URL = 'https://api.bericanlabs.com/v1';

async function listSites() {
  const response = await fetch(`${BASE_URL}/sites`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

async function createSite(data) {
  const response = await fetch(`${BASE_URL}/sites`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(data),
  });

  return response.json();
}

// Usage
const sites = await listSites();
console.log('Your sites:', sites.data);

Python

import os
import requests

API_KEY = os.getenv('BERICAN_API_KEY')
BASE_URL = 'https://api.bericanlabs.com/v1'

def list_sites():
    response = requests.get(
        f'{BASE_URL}/sites',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        }
    )
    response.raise_for_status()
    return response.json()

def create_site(data):
    response = requests.post(
        f'{BASE_URL}/sites',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
        json=data
    )
    response.raise_for_status()
    return response.json()

# Usage
sites = list_sites()
print(f"Your sites: {sites['data']}")

cURL (Shell)

# List all sites
curl -X GET "https://api.bericanlabs.com/v1/sites" \
  -H "Authorization: Bearer $BERICAN_API_KEY"

# Create a new site
curl -X POST "https://api.bericanlabs.com/v1/sites" \
  -H "Authorization: Bearer $BERICAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-site",
    "type": "static",
    "repository": "github.com/user/repo",
    "branch": "main"
  }'

# Deploy a site
curl -X POST "https://api.bericanlabs.com/v1/sites/SITE_ID/deploy" \
  -H "Authorization: Bearer $BERICAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

11Webhooks (Coming Soon)

Webhook support is coming soon! You'll be able to subscribe to events like:

Deployment started
Deployment completed
Deployment failed
Site created
Site deleted
Domain verified
SSL certificate issued

Stay tuned for updates!

API Reference

1Getting Started

2Authentication

3Base URL & Request Format

4Sites API

5Deployments API

6Domains API

7Error Handling

8Rate Limits

9Permissions

10Code Examples

11Webhooks (Coming Soon)

On this page

Related