4.5 KiB
BZOD REST API
Programmatic access to URLs, Landing Pages, QR Codes, Analytics, and Audit Logs.
Overview
The BZOD REST API allows automation and integration with external systems such as:
- Home Assistant
- Shell Scripts
- CI/CD Pipelines
- Monitoring Systems
- Internal Applications
- Self-hosted Services
All API endpoints require authentication using an API Token generated from:
Admin Dashboard → Settings → REST API Tokens
Authentication
Generate an API token from the Admin Dashboard.
Example token:
bzo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Pass the token using the Authorization header.
Example
curl \
-H "Authorization: bzo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://your-domain.com/api/v1/stats
Base URL
https://your-domain.com/api/v1
Example:
https://bzo.in/api/v1
Response Format
Successful responses:
{
"success": true,
"data": {}
}
Error responses:
{
"success": false,
"error": "Invalid API token"
}
URL Management
List URLs
GET /api/v1/urls
Example
curl \
-H "Authorization: TOKEN" \
https://your-domain.com/api/v1/urls
Create URL
POST /api/v1/urls
Request
{
"code": "rust",
"target_url": "https://www.rust-lang.org",
"description": "Rust Language"
}
Example
curl \
-X POST \
-H "Authorization: TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code":"rust",
"target_url":"https://www.rust-lang.org"
}' \
https://your-domain.com/api/v1/urls
Get URL
GET /api/v1/urls/{uuid}
Example:
GET /api/v1/urls/5d4d9e98-7cb7-4c97-9a0a-123456789abc
Update URL
PUT /api/v1/urls/{uuid}
Delete URL
DELETE /api/v1/urls/{uuid}
URL Preview
GET /api/v1/urls/{uuid}/preview
Returns rendered metadata used by preview cards.
Landing Pages
List Pages
GET /api/v1/pages
Create Page
POST /api/v1/pages
Example Request
{
"title": "My Product",
"slug": "product",
"description": "Product Landing Page",
"content": "<h1>Hello World</h1>"
}
Get Page
GET /api/v1/pages/{uuid}
Update Page
PUT /api/v1/pages/{uuid}
Delete Page
DELETE /api/v1/pages/{uuid}
Analytics
Global Statistics
GET /api/v1/stats
Returns overall platform metrics.
Example response:
{
"total_urls": 125,
"total_pages": 12,
"total_clicks": 8431,
"total_qr_scans": 241
}
URL Statistics
GET /api/v1/stats/url/{uuid}
Returns analytics for a single URL.
Landing Page Statistics
GET /api/v1/stats/page/{uuid}
Returns analytics for a single landing page.
QR Codes
Download QR Code
GET /api/v1/qr/{code}
Example:
GET /api/v1/qr/rust
Returns QR image.
Bulk Operations
Bulk QR Export
POST /api/v1/bulk/qr
Generate QR codes for multiple URLs.
Bulk URL Operations
POST /api/v1/bulk/url
Bulk create, update, or manage URLs.
Audit Log
List Audit Events
GET /api/v1/audit
Returns administrative activity history.
Example response:
[
{
"event": "url_created",
"user": "admin",
"timestamp": "2026-06-17T14:30:00Z"
}
]
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Invalid Request |
| 401 | Authentication Failed |
| 403 | Access Denied |
| 404 | Resource Not Found |
| 409 | Conflict |
| 500 | Internal Server Error |
Security Notes
- API tokens are displayed only once during creation.
- Tokens are stored as hashes and cannot be recovered.
- Revoke unused tokens immediately.
- Always use HTTPS.
- Never embed API tokens in public repositories.
Example: Create URL From Shell Script
TOKEN="bzo_xxxxxxxxxxxxxxxxx"
curl \
-X POST \
-H "Authorization: ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"code":"example",
"target_url":"https://example.com"
}' \
https://your-domain.com/api/v1/urls
API Stability
The BZOD API follows semantic versioning.
Current API namespace:
/api/v1
Future breaking changes will be introduced under a new versioned namespace.
Example:
/api/v2