Skip to content

API Reference

ByteFreezer provides a comprehensive REST API for programmatic access to all features.

Base URL

https://api.bytefreezer.com/api/v1

Authentication

All API requests require authentication using a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.bytefreezer.com/api/v1/health

Obtaining a Token

curl -X POST https://api.bytefreezer.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

Response: 

{
  "token": "eyJhbGciOiJIUzI1...",
  "expires_at": "2024-01-16T10:00:00Z",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "role": "account_admin"
  }
}

Common Endpoints

Health Check

GET /api/v1/health

No authentication required. Returns service health status.

Accounts

Method Endpoint Description
GET /api/v1/accounts List all accounts
GET /api/v1/accounts/{id} Get account details
POST /api/v1/accounts Create account
PUT /api/v1/accounts/{id} Update account
DELETE /api/v1/accounts/{id} Delete account

Tenants

Method Endpoint Description
GET /api/v1/accounts/{accountId}/tenants List tenants
GET /api/v1/tenants/{id} Get tenant details
POST /api/v1/accounts/{accountId}/tenants Create tenant
PUT /api/v1/accounts/{accountId}/tenants/{id} Update tenant
DELETE /api/v1/accounts/{accountId}/tenants/{id} Delete tenant

Datasets

Method Endpoint Description
GET /api/v1/tenants/{tenantId}/datasets List datasets
GET /api/v1/tenants/{tenantId}/datasets/{id} Get dataset details
POST /api/v1/tenants/{tenantId}/datasets Create dataset
PUT /api/v1/tenants/{tenantId}/datasets/{id} Update dataset
DELETE /api/v1/tenants/{tenantId}/datasets/{id} Delete dataset

Transformations

Method Endpoint Description
GET /api/v1/tenants/{tenantId}/datasets/{datasetId}/transformations Get active config
POST /api/v1/tenants/{tenantId}/datasets/{datasetId}/transformations/test Test transformation
POST /api/v1/tenants/{tenantId}/datasets/{datasetId}/transformations/activate Activate transformation

Enrichers

Method Endpoint Description
GET /api/v1/tenants/{tenantId}/enrichers List enrichers
GET /api/v1/tenants/{tenantId}/enrichers/{id} Get enricher details
POST /api/v1/tenants/{tenantId}/enrichers Create enricher
POST /api/v1/tenants/{tenantId}/enrichers/{id}/upload Upload enricher data
DELETE /api/v1/tenants/{tenantId}/enrichers/{id} Delete enricher

Error Responses

All errors return a consistent JSON format:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "status": 400
}

Common Error Codes

Code HTTP Status Description
UNAUTHORIZED 401 Invalid or missing authentication
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
VALIDATION_ERROR 400 Invalid request data
INTERNAL_ERROR 500 Server error

Rate Limiting

API requests are rate-limited per user. Default limits:

  • 100 requests per minute
  • Burst of 20 requests

Rate limit headers are included in responses:

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

Interactive Documentation

For interactive API exploration, visit the Swagger UI at:

https://api.bytefreezer.com/v1/docs