REST API Reference
Complete reference for the Lubes REST API. All endpoints return JSON.
Base URL
https://api.lubes.dev/v1All API endpoints are prefixed with this base URL. For example, to list projects:
GET https://api.lubes.dev/v1/projectsAuthentication
The API uses Bearer token authentication. Include your API key in the Authorization header:
curl https://api.lubes.dev/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Getting an API Key
You can create API keys in the dashboard settings. Each key can be scoped to specific projects and permissions.
Security tip: Never commit API keys to version control. Use environment variables or a secrets manager in production.
Request Format
Headers
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer YOUR_API_KEY | Yes |
| Content-Type | application/json | For POST/PATCH |
| X-Project-ID | Your project ID | For project-scoped endpoints |
Pagination
List endpoints support pagination via query parameters:
GET /projects?limit=20&offset=0
# Response includes pagination info:
{
"data": [...],
"pagination": {
"total": 100,
"limit": 20,
"offset": 0,
"has_more": true
}
}Error Handling
The API uses conventional HTTP status codes. Errors return a JSON object with details:
{
"error": {
"code": "validation_error",
"message": "Invalid email format",
"details": {
"field": "email",
"constraint": "email"
}
}
}Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | No content (successful delete) |
| 400 | Bad request - invalid parameters |
| 401 | Unauthorized - invalid or missing token |
| 403 | Forbidden - insufficient permissions |
| 404 | Not found |
| 422 | Validation error |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Endpoints
Authentication
POST
/auth/registerRegister a new userPOST
/auth/loginLog in with email/passwordPOST
/auth/logoutLog out current sessionPOST
/auth/refreshRefresh access tokenGET
/auth/meGet current userPOST
/auth/forgot-passwordRequest password resetPOST
/auth/reset-passwordReset password with tokenOrganizations
GET
/organizationsList organizationsPOST
/organizationsCreate organizationGET
/organizations/:idGet organizationPATCH
/organizations/:idUpdate organizationDELETE
/organizations/:idDelete organizationGET
/organizations/:id/membersList membersPOST
/organizations/:id/membersInvite memberProjects
GET
/projectsList projectsPOST
/projectsCreate projectGET
/projects/:idGet projectPATCH
/projects/:idUpdate projectDELETE
/projects/:idDelete projectDatabase
POST
/projects/:id/db/queryExecute SQL queryGET
/projects/:id/db/tablesList tablesGET
/projects/:id/db/tables/:tableGet table schemaGET
/projects/:id/db/branchesList branchesPOST
/projects/:id/db/branchesCreate branchGET
/projects/:id/db/migrationsList migrationsPOST
/projects/:id/db/migrationsRun migrationFunctions
GET
/projects/:id/functionsList functionsPOST
/projects/:id/functionsCreate functionGET
/projects/:id/functions/:slugGet functionPATCH
/projects/:id/functions/:slugUpdate functionDELETE
/projects/:id/functions/:slugDelete functionPOST
/projects/:id/functions/:slug/deployDeploy functionGET
/projects/:id/functions/:slug/logsGet function logsStorage
GET
/projects/:id/storage/bucketsList bucketsPOST
/projects/:id/storage/bucketsCreate bucketDELETE
/projects/:id/storage/buckets/:nameDelete bucketGET
/projects/:id/storage/objectsList objectsPOST
/projects/:id/storage/objectsUpload objectGET
/projects/:id/storage/objects/:keyDownload objectDELETE
/projects/:id/storage/objects/:keyDelete objectPOST
/projects/:id/storage/signCreate signed URLDeployments
GET
/projects/:id/deploymentsList deploymentsPOST
/projects/:id/deploymentsCreate deploymentGET
/projects/:id/deployments/:deployIdGet deploymentPOST
/projects/:id/deployments/:deployId/rollbackRollback deploymentGET
/projects/:id/deployments/:deployId/logsGet deployment logsEnvironment Variables
GET
/projects/:id/envList environment variablesPOST
/projects/:id/envSet environment variableDELETE
/projects/:id/env/:keyDelete environment variableExample Requests
Create a Project
curl -X POST https://api.lubes.dev/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Project",
"organization_id": "org_123"
}'
# Response:
{
"id": "proj_456",
"name": "My Project",
"slug": "my-project",
"organization_id": "org_123",
"created_at": "2024-01-15T10:30:00Z"
}Execute a Query
curl -X POST https://api.lubes.dev/v1/projects/proj_456/db/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT * FROM users WHERE status = $1",
"params": ["active"]
}'
# Response:
{
"rows": [
{ "id": "1", "email": "user@example.com", "status": "active" }
],
"row_count": 1,
"execution_time_ms": 12
}Upload a File
curl -X POST https://api.lubes.dev/v1/projects/proj_456/storage/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "bucket=avatars" \
-F "file=@/path/to/avatar.png"
# Response:
{
"key": "avatars/abc123.png",
"url": "https://storage.lubes.dev/proj_456/avatars/abc123.png",
"size": 12345,
"content_type": "image/png"
}Rate Limits
Rate limits vary by plan. Current limits are returned in response headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Requests allowed per minute |
| X-RateLimit-Remaining | Requests remaining in window |
| X-RateLimit-Reset | Unix timestamp when limit resets |
Free
100
requests/minute
Pro
1,000
requests/minute
Team
10,000
requests/minute