REST API Reference
Query and control ButterStack programmatically using the REST API.
Base URL
https://api.butterstack.com/v1
Authentication
All requests require a Bearer token in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.butterstack.com/v1/projects
See Authentication Guide for details on obtaining API keys.
Projects
List Projects
GET /v1/projects
Response:
{
"projects": [
{
"id": "proj_abc123",
"name": "MyGame",
"engine": "unreal",
"created_at": "2026-12-01T10:00:00Z"
}
]
}
Get Project
GET /v1/projects/:project_id
Builds
List Builds
GET /v1/projects/:project_id/builds
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by status: pending, running, success, failed |
| limit | integer | Max results (default: 20, max: 100) |
| offset | integer | Pagination offset |
Get Build
GET /v1/builds/:build_id
Response:
{
"id": "build_xyz789",
"project_id": "proj_abc123",
"status": "success",
"duration_seconds": 1234,
"started_at": "2026-12-15T14:30:00Z",
"finished_at": "2026-12-15T14:50:34Z",
"changelist": "12345",
"artifacts": [
{
"name": "Game-Win64-Shipping.zip",
"size_bytes": 1234567890,
"url": "https://..."
}
]
}
Trigger Build
POST /v1/projects/:project_id/builds
Request Body:
{
"platform": "win64",
"configuration": "shipping",
"changelist": "latest"
}
Assets
List Assets
GET /v1/projects/:project_id/assets
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| path | string | Filter by depot path prefix |
| type | string | Filter by asset type |
| status | string | Filter by approval status |
Get Asset
GET /v1/assets/:asset_id
Update Asset Status
PATCH /v1/assets/:asset_id
Request Body:
{
"approval_status": "approved"
}
Changelists
List Changelists
GET /v1/projects/:project_id/changelists
Get Changelist
GET /v1/changelists/:changelist_id
Response:
{
"id": "cl_12345",
"number": 12345,
"author": "john.doe",
"description": "Updated character model textures",
"submitted_at": "2026-12-15T10:00:00Z",
"files": [
{
"path": "//depot/Game/Content/Characters/Warrior/T_Warrior_D.uasset",
"action": "edit"
}
]
}
Deployments
List Deployments
GET /v1/projects/:project_id/deployments
Get Deployment
GET /v1/deployments/:deployment_id
Response:
{
"id": "deploy_abc123",
"build_id": "build_xyz789",
"platform": "steam",
"status": "live",
"branch": "beta",
"deployed_at": "2026-12-15T16:00:00Z"
}
Error Responses
All errors follow this format:
{
"error": "error_code",
"message": "Human-readable description"
}
Common Error Codes
| Code | HTTP Status | Description |
|---|---|---|
| unauthorized | 401 | Invalid or missing auth token |
| forbidden | 403 | Token lacks required permissions |
| not_found | 404 | Resource not found |
| rate_limited | 429 | Too many requests |
| server_error | 500 | Internal server error |
Rate Limits
- Default: 60 requests/minute per API key
- Burst: Up to 10 requests/second
Rate limit headers in responses:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702656000
Related
- Authentication - API keys and tokens
- Webhooks - Inbound webhook endpoints