Berican LabsBerican Labs
API Documentation

Berican Labs API Reference

Complete REST API documentation with interactive examples. Manage sites, deployments, domains, and webhooks programmatically.

30+ Endpoints

API Key Auth

100 req/min

Production Ready

Getting Started

Learn how to authenticate and make your first API request

Authentication

The Berican API uses API keys for authentication. Include your API key in the Authorization header of each request.

Authorization Header:

Authorization: Bearer YOUR_API_KEY

Get Your API Key

Generate API keys from your Dashboard → API Keys. You can create multiple keys with different permissions.

Example Request

curl https://bericanlabs.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Rate Limits

All API endpoints are rate limited to ensure fair usage and system stability.

100

requests per minute

429

status code when exceeded

Rate limit headers are included in every API response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Error Handling

The API uses standard HTTP status codes to indicate success or failure. All errors return JSON with an error message.

200OK - Request succeeded
201Created - Resource created successfully
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

Error Response Format:

{
  "error": "Invalid site type",
  "details": "Type must be 'static' or 'wordpress'",
  "received": "invalid"
}

Sites API

Create and manage static sites and WordPress installations

GET/api/v1/sites
List all sites

Retrieve a paginated list of all sites for the authenticated user. Supports filtering by type and status.

Required (sites:read permission)
100 requests/minute

Query Parameters

pageinteger

Page number for pagination

Example: 1
limitinteger

Number of results per page (max: 100)

Example: 25
typestring

Filter by site type: 'static' or 'wordpress'

Example: static
statusstring

Filter by status: 'active', 'pending', 'provisioning', 'error', 'stopped'

Example: active

Response

200Success
{
  "data": [
    {
      "id": "site_abc123",
      "name": "My Portfolio",
      "slug": "my-portfolio",
      "type": "static",
      "status": "active",
      "url": "https://my-portfolio.bericanlabs.com",
      "subdomain": "my-portfolio",
      "repository": {
        "url": "github.com/user/portfolio",
        "branch": "main"
      },
      "domains": [
        {
          "id": "dom_xyz789",
          "name": "example.com",
          "status": "active"
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}

Code Examples

curl https://bericanlabs.com/api/v1/sites?page=1&limit=25 \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/api/v1/sites
Create a new site

Create a new static site or WordPress installation. The site will be provisioned asynchronously.

Required (sites:write permission)
100 requests/minute

Request Body

Site configuration

{
  "name": "My Awesome Site",
  "type": "static",
  "repository": "github.com/username/repo",
  "branch": "main"
}

Response

201Created
{
  "data": {
    "id": "site_abc123",
    "name": "My Awesome Site",
    "slug": "my-awesome-site",
    "type": "static",
    "status": "pending",
    "url": "https://my-awesome-site.bericanlabs.com",
    "subdomain": "my-awesome-site",
    "repository": {
      "url": "github.com/username/repo",
      "branch": "main"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "message": "Site created successfully. Provisioning will begin shortly."
}

Code Examples

curl -X POST https://bericanlabs.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Awesome Site",
    "type": "static",
    "repository": "github.com/username/repo",
    "branch": "main"
  }'
Try it out

Get your API key from Dashboard → API Keys

GET/api/v1/sites/:id
Get site details

Retrieve detailed information about a specific site.

Required (sites:read permission)
100 requests/minute

Path Parameters

idstringrequired

Site ID

Example: site_abc123

Response

200
{
  "id": "site_abc123",
  "name": "My Portfolio",
  "slug": "my-portfolio",
  "type": "static",
  "status": "active",
  "url": "https://my-portfolio.bericanlabs.com",
  "subdomain": "my-portfolio",
  "repository": {
    "url": "github.com/user/portfolio",
    "branch": "main"
  },
  "domains": [],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Code Examples

curl https://bericanlabs.com/api/v1/sites/site_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/api/v1/sites/:id/deploy
Trigger deployment

Manually trigger a deployment for a site. The deployment will run asynchronously.

Required (sites:write permission)
100 requests/minute

Path Parameters

idstringrequired

Site ID

Example: site_abc123

Response

200
{
  "message": "Deployment triggered successfully",
  "deploymentId": "dep_xyz789",
  "status": "pending"
}

Code Examples

curl -X POST https://bericanlabs.com/api/v1/sites/site_abc123/deploy \
  -H "Authorization: Bearer YOUR_API_KEY"
DELETE/api/v1/sites/:id
Delete a site

Permanently delete a site and all associated resources.

Required (sites:delete permission)
100 requests/minute

Path Parameters

idstringrequired

Site ID

Example: site_abc123

Response

200
{
  "message": "Site deleted successfully"
}

Code Examples

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

Domains API

Manage custom domains and check availability

GET/api/v1/domains
List all domains

Retrieve a list of all domains associated with your sites.

Required (domains:read permission)
100 requests/minute

Response

200
{
  "data": [
    {
      "id": "dom_xyz789",
      "name": "example.com",
      "status": "active",
      "sslStatus": "active",
      "siteId": "site_abc123",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Code Examples

curl https://bericanlabs.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/api/v1/domains/check
Check domain availability

Check if a domain is available for registration or transfer.

Required
100 requests/minute

Request Body

{
  "domain": "example.com"
}

Response

200
{
  "domain": "example.com",
  "available": true,
  "price": 1200,
  "currency": "KES"
}

Deployments API

Monitor and manage site deployments

GET/api/v1/deployments/:id
Get deployment details

Retrieve information about a specific deployment.

Required
100 requests/minute

Path Parameters

idstringrequired

Deployment ID

Example: dep_xyz789

Response

200
{
  "id": "dep_xyz789",
  "siteId": "site_abc123",
  "status": "success",
  "commitHash": "abc123def456",
  "branch": "main",
  "startedAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:00Z",
  "duration": 120
}
GET/api/v1/deployments/:id/logs
Get deployment logs

Retrieve logs for a specific deployment.

Required
100 requests/minute

Path Parameters

idstringrequired

Deployment ID

Example: dep_xyz789

Response

200
{
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "info",
      "message": "Starting deployment..."
    },
    {
      "timestamp": "2024-01-15T10:30:05Z",
      "level": "info",
      "message": "Building site..."
    }
  ]
}

Webhooks API

Configure webhooks for real-time event notifications

GET/api/v1/webhooks
List all webhooks

Retrieve a list of all configured webhooks.

Required
100 requests/minute

Response

200
{
  "data": [
    {
      "id": "hook_abc123",
      "url": "https://example.com/webhook",
      "events": ["deployment.success", "deployment.failed"],
      "active": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}
POST/api/v1/webhooks
Create a webhook

Create a new webhook to receive event notifications.

Required
100 requests/minute

Request Body

{
  "url": "https://example.com/webhook",
  "events": ["deployment.success", "deployment.failed"],
  "secret": "your-webhook-secret"
}

Response

201
{
  "id": "hook_abc123",
  "url": "https://example.com/webhook",
  "events": ["deployment.success", "deployment.failed"],
  "active": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Ready to build?

Get your API key and start deploying sites, managing domains, and automating your workflow.