REST API

Vibora exposes a REST API for programmatic access to task management and server features.

Base URL

http://localhost:7777/api

Authentication

The API currently does not require authentication. When running on a remote server, secure access via SSH tunneling or reverse proxy.

Tasks

List Tasks

GET /api/tasks

Query Parameters:

Name	Type	Description
status	string	Filter by status
repositoryId	string	Filter by repository

Response:

[
  {
    "id": "abc123",
    "title": "Add authentication",
    "status": "IN_PROGRESS",
    "repositoryId": "repo456",
    "worktreePath": "/home/user/.vibora/worktrees/task-abc123",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:20:00Z"
  }
]

Get Task

GET /api/tasks/:id

Response:

{
  "id": "abc123",
  "title": "Add authentication",
  "description": "Implement user login and registration",
  "status": "IN_PROGRESS",
  "repositoryId": "repo456",
  "worktreePath": "/home/user/.vibora/worktrees/task-abc123",
  "prUrl": "https://github.com/org/repo/pull/42",
  "linearUrl": "https://linear.app/team/issue/TEAM-123",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:20:00Z"
}

Create Task

POST /api/tasks

Body:

{
  "title": "Add authentication",
  "description": "Implement user login",
  "repositoryId": "repo456",
  "baseBranch": "main"
}

Update Task

PATCH /api/tasks/:id

Body:

{
  "title": "Updated title",
  "description": "Updated description"
}

Update Task Status

PATCH /api/tasks/:id/status

Body:

{
  "status": "IN_REVIEW"
}

Delete Task

DELETE /api/tasks/:id

Repositories

List Repositories

GET /api/repositories

Response:

[
  {
    "id": "repo456",
    "name": "my-project",
    "path": "/home/user/projects/my-project",
    "defaultBranch": "main"
  }
]

Get Repository

GET /api/repositories/:id

Create Repository

POST /api/repositories

Body:

{
  "path": "/home/user/projects/my-project"
}

Delete Repository

DELETE /api/repositories/:id

Apps

List Apps

GET /api/apps

Response:

[
  {
    "id": "app123",
    "name": "my-app",
    "repositoryId": "repo456",
    "status": "running",
    "composeFile": "docker-compose.yml",
    "autoDeployEnabled": false,
    "services": [
      {
        "serviceName": "web",
        "containerPort": 3000,
        "exposed": true,
        "domain": "myapp.example.com"
      }
    ]
  }
]

Get App

GET /api/apps/:id

Create App

POST /api/apps

Body:

{
  "name": "my-app",
  "repositoryId": "repo456",
  "branch": "main",
  "composeFile": "docker-compose.yml",
  "services": [
    {
      "serviceName": "web",
      "containerPort": 3000,
      "exposed": true,
      "domain": "myapp.example.com"
    }
  ]
}

Update App

PATCH /api/apps/:id

Body:

{
  "name": "updated-name",
  "autoDeployEnabled": true,
  "notificationsEnabled": true,
  "environmentVariables": {
    "DATABASE_URL": "postgres://..."
  },
  "services": [
    {
      "serviceName": "web",
      "containerPort": 3000,
      "exposed": true,
      "domain": "myapp.example.com"
    }
  ]
}

Delete App

DELETE /api/apps/:id

Stops all containers and removes the Docker stack.

Query Parameters:

Name	Type	Description
stopContainers	boolean	Whether to stop containers (default: true)

Deploy App

POST /api/apps/:id/deploy

Triggers a deployment. Returns immediately; check deployments for status.

Response:

{
  "success": true,
  "deployment": {
    "id": "deploy123",
    "status": "building",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Deploy App (Streaming)

GET /api/apps/:id/deploy/stream

Server-Sent Events endpoint for real-time deployment progress.

Events:

• progress — Build progress updates
• complete — Deployment finished successfully
• error — Deployment failed

Stop App

POST /api/apps/:id/stop

Stops all containers without deleting the app.

Cancel Deployment

POST /api/apps/:id/cancel-deploy

Cancels an in-progress deployment.

Get App Logs

GET /api/apps/:id/logs

Query Parameters:

Name	Type	Description
service	string	Filter by service name
tail	number	Number of lines (default: 100)

Get App Status

GET /api/apps/:id/status

Response:

{
  "containers": [
    {
      "name": "myapp_web.1",
      "status": "running",
      "state": "Running"
    }
  ]
}

Get Deployments

GET /api/apps/:id/deployments

Returns the last 10 deployments for the app.

Sync Services

POST /api/apps/:id/sync-services

Re-parses the compose file and updates service ports.

Deployment Settings

Get Prerequisites

GET /api/deployment/prerequisites

Check if Docker, Traefik, and other prerequisites are configured.

Response:

{
  "docker": {
    "installed": true,
    "running": true,
    "version": "24.0.7"
  },
  "traefik": {
    "detected": true,
    "type": "vibora",
    "containerName": "traefik",
    "network": "traefik"
  },
  "settings": {
    "cloudflareConfigured": true
  },
  "ready": true
}

Get Deployment Settings

GET /api/deployment/settings

Update Deployment Settings

POST /api/deployment/settings

Body:

{
  "cloudflareApiToken": "your-token"
}

Start Traefik

POST /api/deployment/traefik/start

Starts Vibora's managed Traefik container.

Stop Traefik

POST /api/deployment/traefik/stop

Terminals

List Terminals

GET /api/terminals

Create Terminal

POST /api/terminals

Body:

{
  "name": "My Terminal",
  "cwd": "/home/user/projects"
}

Delete Terminal

DELETE /api/terminals/:id

Worktrees

List Worktrees

GET /api/worktrees

Delete Worktree

DELETE /api/worktrees/:path

Git Operations

Repository Status

GET /api/git/status?path=/path/to/repo

Repository Diff

GET /api/git/diff?path=/path/to/repo

List Branches

GET /api/git/branches?path=/path/to/repo

Notifications

Send Notification

POST /api/notifications

Body:

{
  "title": "Task Complete",
  "message": "Authentication feature is ready for review"
}

Health

Health Check

GET /api/health

Response:

{
  "status": "ok",
  "version": "1.0.0"
}

WebSocket

Terminal I/O is handled via WebSocket:

ws://localhost:7777/ws/terminal

Protocol

Messages are JSON-encoded:

{
  "type": "input",
  "terminalId": "term123",
  "data": "ls -la\n"
}

{
  "type": "output",
  "terminalId": "term123",
  "data": "total 48\ndrwxr-xr-x..."
}

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "Task not found",
  "code": "NOT_FOUND"
}

Status	Description
400	Bad Request — Invalid input
404	Not Found — Resource doesn't exist
500	Internal Server Error