API Reference

Burrito provides a REST API for programmatic access to all platform features. The base URL is https://console.bntso.com/api/v1.

Authentication

All endpoints (except register and login) require an Authorization header:

Authorization: Bearer YOUR_API_KEY

You receive your API key when you register or log in.

Error Responses

All errors return JSON with an error field:

{"error": "description of what went wrong"}

Common status codes: 400 (bad request), 401 (not authenticated), 404 (not found), 409 (conflict), 500 (internal error).

Auth

Register

POST /api/v1/auth/register

Create a new account. No authentication required.

Request body:

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "secret123"
}

Response (201 Created):

{
  "user": {
    "id": 1,
    "username": "alice",
    "email": "alice@example.com",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "api_key": "a1b2c3..."
}

Login

POST /api/v1/auth/login

Log in to an existing account. No authentication required.

Request body:

{
  "email": "alice@example.com",
  "password": "secret123"
}

Response (200 OK): Same shape as register.

Get Current User

GET /api/v1/me

Response (200 OK):

{
  "user": {
    "id": 1,
    "username": "alice",
    "email": "alice@example.com",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

SSH Keys

Add SSH Key

POST /api/v1/ssh-keys

Request body:

{
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAA... alice@laptop"
}

Response (201 Created):

{
  "id": 1,
  "user_id": 1,
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAA... alice@laptop",
  "fingerprint": "SHA256:...",
  "created_at": "2025-01-15T10:30:00Z"
}

List SSH Keys

GET /api/v1/ssh-keys

Response (200 OK): Array of SSH key objects (same shape as above).

Delete SSH Key

DELETE /api/v1/ssh-keys/{id}

Response: 204 No Content

Sites

Create Site

POST /api/v1/sites

Request body:

{
  "name": "myapp"
}

Site names must be 3-63 characters, lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Reserved names (api, app, git, www, mail, admin, test) cannot be used.

Response (201 Created):

{
  "site": {
    "id": 1,
    "user_id": 1,
    "name": "myapp",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "environments": [
    {
      "id": 1,
      "site_id": 1,
      "name": "prod",
      "container_state": "stopped",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "site_id": 1,
      "name": "test",
      "container_state": "stopped",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "git_url": "git@git.bntso.com:myapp.git"
}

List Sites

GET /api/v1/sites

Response (200 OK): Array of site objects.

Get Site

GET /api/v1/sites/{name}

Response (200 OK):

{
  "site": {
    "id": 1,
    "user_id": 1,
    "name": "myapp",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "environments": [
    {
      "id": 1,
      "site_id": 1,
      "name": "prod",
      "active_deployment_id": 5,
      "container_id": "abc123...",
      "port": 10042,
      "container_state": "running",
      "last_request_at": "2025-01-15T12:00:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Delete Site

DELETE /api/v1/sites/{name}

Removes DNS records, deletes the git repository, and deletes all site data.

Response: 204 No Content

Deployments

List Deployments

GET /api/v1/sites/{name}/deployments

Response (200 OK): Array of deployment objects.

Get Deployment

GET /api/v1/sites/{name}/deployments/{id}

Response (200 OK):

{
  "id": 5,
  "environment_id": 1,
  "commit_sha": "abc123def456...",
  "image_tag": "myapp-prod-abc123de",
  "container_port": 3000,
  "status": "live",
  "build_log": "Step 1/5 : FROM node:20-alpine\n...",
  "created_at": "2025-01-15T11:00:00Z",
  "finished_at": "2025-01-15T11:01:00Z"
}

Deployment status values: pending, building, built, deploying, live, failed, superseded.

Upload and Deploy

POST /api/v1/sites/{name}/deploy

Upload a file (zip, tar, tar.gz, or tgz) containing a Dockerfile and your source code to trigger a new deployment. The build runs asynchronously.

Request: multipart/form-data

Example:

curl -X POST https://console.bntso.com/api/v1/sites/myapp/deploy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@myapp.zip" \
  -F "environment=prod"

Response (202 Accepted):

{
  "deployment_id": 7,
  "environment": "prod",
  "content_hash": "a1b2c3d4...",
  "status": "accepted"
}

Rollback

POST /api/v1/sites/{name}/deployments/{id}/rollback

Creates a new deployment using the image from the specified deployment. No request body required.

Response (202 Accepted): The new deployment object. The deploy happens asynchronously.

Environments

Promote Test to Production

POST /api/v1/sites/{name}/environments/test/promote

Copies the active deployment from the test environment to production using the same container image. No request body required.

Response (202 Accepted): The new production deployment object.