biver-builder

What this skill does

# Biver Builder API Skill

## Before You Install

> **Security Checklist**
>
> Before installing or supplying credentials, please review:
>
> 1. **Credential Required**: This skill requires `BIVER_API_KEY` to operate
> 2. **Start with Test Keys**: Use `bvr_test_` prefix keys for initial testing — never use `bvr_live_` keys until you trust the skill
> 3. **Verify Scopes**: Check required API key scopes below and use least-privilege principle
> 4. **Rotate Keys**: Periodically rotate your API keys for security
> 5. **Inspect Source**: If using manual installation, inspect the GitHub repository code before cloning

---

## Installation

### Via ClawdHub (Recommended)
```bash
clawdhub install biver-builder
```

### Manual

> **Warning**: Cloning external repositories can introduce arbitrary code. **Inspect the repository first** before running:
>
> ```bash
> # Step 1: Review the source code
> git clone https://github.com/RamaAditya49/biver-builder.git /tmp/biver-builder-review
> # Review files in /tmp/biver-builder-review before proceeding
>
> # Step 2: Only after review, install to your skills directory
> git clone https://github.com/RamaAditya49/biver-builder.git ~/.openclaw/skills/biver-builder
> ```

---

## Credential Configuration

### Required Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `BIVER_API_KEY` | Your Biver API key | `bvr_live_xxxxx` or `bvr_test_xxxxx` |

### Optional Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `BIVER_API_BASE_URL` | Custom API base URL | `https://api.biver.id` |

### Setting Up Credentials

**Via OpenClaw Dashboard:**
1. Navigate to Settings > Environment Variables
2. Add `BIVER_API_KEY` with your API key value
3. (Optional) Add `BIVER_API_BASE_URL` for custom endpoints

**Security Best Practices:**
- Use `bvr_test_` prefix keys for development/testing
- Use `bvr_live_` prefix keys only in production **after you trust the skill**
- **Verify required scopes** before creating your API key — only grant minimum permissions needed
- Never commit API keys to version control
- Rotate keys periodically
- **Do not supply credentials** until you have reviewed the skill or confirmed it from a verified source

### How to Get Your API Key

1. Log in to [Biver Dashboard](https://biver.id)
2. Go to **Settings** > **API Keys**
3. Click **Generate New Key**
4. **Select required scopes** (see Required Scopes section below — grant only what you need)
5. Choose key type: `bvr_test_` for testing, `bvr_live_` for production
6. Copy and store securely (shown only once)

> **Scope Recommendation**: Start with read-only scopes (`*:read`) for testing. Add write scopes only when needed.

---

## Quick Reference

### Base URL
```
https://api.biver.id
```

### Authentication Headers
```typescript
// Use environment variables for security
const apiKey = process.env.BIVER_API_KEY;

// Headers configuration
{
  'X-API-Key': apiKey,
  'Authorization': `Bearer ${apiKey}`
}
```

### API Key Prefixes
| Prefix | Environment | Usage |
|--------|-------------|-------|
| `bvr_live_` | Production | Real data operations |
| `bvr_test_` | Sandbox | Testing without affecting real data |

### Endpoint Lookup

| Task | Endpoint | Method | Auth | Scope |
|------|----------|--------|------|-------|
| List pages | `/v1/pages` | GET | Yes | pages:read |
| Create page | `/v1/pages` | POST | Yes | pages:write |
| Get page | `/v1/pages/:id` | GET | Yes | pages:read |
| Update page | `/v1/pages/:id` | PATCH | Yes | pages:write |
| Delete page | `/v1/pages/:id` | DELETE | Yes | pages:write |
| Deploy page | `/v1/pages/:id/deploy` | POST | Yes | pages:write |
| List subdomains | `/v1/subdomains` | GET | Yes | pages:read |
| Create subdomain | `/v1/subdomains` | POST | Yes | pages:write |
| Update subdomain | `/v1/subdomains/:id` | PATCH | Yes | pages:write |
| Delete subdomain | `/v1/subdomains/:id` | DELETE | Yes | pages:write |
| List domains | `/v1/domains` | GET | Yes | domains:read |
| Add custom domain | `/v1/domains` | POST | Yes | domains:write |
| Set primary domain | `/v1/domains/:id/primary` | POST | Yes | domains:write |
| Delete domain | `/v1/domains/:id` | DELETE | Yes | domains:write |
| List sections | `/v1/sections` | GET | Yes | sections:read |
| Create section | `/v1/sections` | POST | Yes | sections:write |
| Update section | `/v1/sections/:id` | PATCH | Yes | sections:write |
| Delete section | `/v1/sections/:id` | DELETE | Yes | sections:write |
| List products | `/v1/products` | GET | Yes | products:read |
| Create product | `/v1/products` | POST | Yes | products:write |
| Update product | `/v1/products/:id` | PATCH | Yes | products:write |
| Delete product | `/v1/products/:id` | DELETE | Yes | products:write |
| List forms | `/v1/forms` | GET | Yes | forms:read |
| Create form | `/v1/forms` | POST | Yes | forms:write |
| Get submissions | `/v1/forms/:id/submissions` | GET | Yes | forms:read |
| Submit form | `/v1/forms/:id/submit` | POST | **No** | - |
| List gallery | `/v1/gallery` | GET | Yes | gallery:read |
| Upload asset | `/v1/gallery` | POST | Yes | gallery:read |
| Delete asset | `/v1/gallery/:id` | DELETE | Yes | gallery:read |
| Get workspace | `/v1/workspace/settings` | GET | Yes | workspace:read |
| Update workspace | `/v1/workspace/settings` | PUT | Yes | workspace:write |
| Update branding | `/v1/workspace/branding` | PUT | Yes | workspace:write |
| Update SEO | `/v1/workspace/seo` | PUT | Yes | workspace:write |
| AI generate page | `/v1/ai/pages` | POST | Yes | ai:generate |
| AI generate section | `/v1/ai/sections` | POST | Yes | ai:generate |
| Health check | `/health` | GET | **No** | - |

---

## Authentication

### Required Scopes

| Scope | Description |
|-------|-------------|
| `pages:read` | Read pages |
| `pages:write` | Create, update, delete pages |
| `sections:read` | Read sections |
| `sections:write` | Create, update, delete sections |
| `products:read` | Read products |
| `products:write` | Manage product catalog |
| `forms:read` | Read forms and submissions |
| `forms:write` | Create/update forms |
| `gallery:read` | Access gallery assets |
| `domains:read` | View custom domains |
| `domains:write` | Add/remove custom domains |
| `subdomains:read` | View subdomains |
| `subdomains:write` | Create/update/delete subdomains |
| `workspace:read` | Read workspace settings |
| `workspace:write` | Update workspace settings |
| `ai:generate` | Generate pages/sections with AI |

---

## Common Workflows

### Workflow 1: Create Landing Page with Subdomain

```typescript
const API_KEY = process.env.BIVER_API_KEY;
const BASE_URL = process.env.BIVER_API_BASE_URL || 'https://api.biver.id';

// Step 1: Create subdomain
const subdomain = await fetch(`${BASE_URL}/v1/subdomains`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    subdomain: 'my-store',
    title: 'Summer Sale 2026',
    description: 'Our biggest sale event',
    pathSlug: 'summer-sale'
  })
});
// Result: my-store.lp.biver.id/summer-sale

// Step 2: Create sections for the page
const section = await fetch(`${BASE_URL}/v1/sections?pageId=PAGE_ID`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    type: 'hero',
    name: 'Hero Section',
    htmlContent: '<div class="hero">...</div>',
    cssContent: '.hero { ... }',
    visible: true,
    order: 0
  })
});

// Step 3: Update subdomain status to publish
await fetch(`${BASE_URL}/v1/subdomains/${subdomainId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    status: 'published'
  })
});
```

### Workflow 2: Setup Custom Domain

```typescript
const API_KEY = process.env.BIVER_API_KEY;
const BASE_URL = process.env.BIVER_API_BASE_URL || 'https://api.biver.id';

// Step 1: Add