API Reference

Viban exposes APIs for programmatic access. The primary API is the RPC API used by the frontend, with additional REST-style endpoints for specific use cases.

Base URL

Development: http://localhost:7771/api

For production, use your configured domain.

Authentication

Most API requests require authentication via session cookies (set during OAuth login).

For programmatic access:

1. Use the test login endpoint (if enabled)
2. Or integrate with the OAuth flow

RPC API

The primary API uses a single RPC endpoint with action-specific payloads.

Endpoint

POST /api/rpc/run
Content-Type: application/json

Request Format

{
  "action": "action_name",
  "input": {
    "field1": "value1",
    "field2": "value2"
  }
}

Available Actions

Actions are generated by AshTypescript and defined in the frontend SDK (frontend/src/lib/generated/ash.ts).

Board Actions

Action	Description
create_board	Create a new board
list_boards	List all boards
get_board	Get a specific board
update_board	Update board properties
destroy_board	Delete a board

Task Actions

Action	Description
create_task	Create a new task
list_tasks	List tasks (with filtering)
get_task	Get task details
update_task	Update task properties
move_task	Move task to different column
destroy_task	Delete a task
refine_task	AI-refine task description
refine_preview	Preview task refinement
generate_subtasks	Generate subtasks from task
create_task_pr	Create a PR for task changes
clear_task_error	Clear task error state

Column Actions

Action	Description
create_column	Create a new column
list_columns	List columns for a board
update_column	Update column properties
destroy_column	Delete a column
update_column_settings	Update column settings

Hook Actions

Action	Description
create_hook	Create a custom hook
create_script_hook	Create a script hook
create_agent_hook	Create an agent hook
list_hooks	List hooks for a board
update_hook	Update hook properties
destroy_hook	Delete a hook

Repository Actions

Action	Description
create_repository	Connect a repository
list_repositories	List repositories
list_branches	List branches for a repo

Example: Create Task

curl -X POST http://localhost:7771/api/rpc/run \
  -H "Content-Type: application/json" \
  -b "session_cookie_here" \
  -d '{
    "action": "create_task",
    "input": {
      "title": "Add authentication",
      "description": "Implement user login...",
      "column_id": "uuid-of-column"
    }
  }'

REST Endpoints

Some functionality is exposed via traditional REST endpoints:

Health Check

GET /api/health

Returns server health status.

Hooks

GET /api/boards/:board_id/hooks

List all hooks (system + custom) for a board.

GET /api/hooks/system

List all available system hooks.

VCS Integration

GET /api/vcs/repos

List repositories from connected VCS provider.

GET /api/vcs/repos/:owner/:repo/branches

List branches for a repository.

Pull Requests

GET /api/vcs/repos/:owner/:repo/pulls

List pull requests.

POST /api/vcs/repos/:owner/:repo/pulls

Create a new pull request.

Task Images

GET /api/tasks/:task_id/images/:image_id

Retrieve an image attached to a task.

Electric SQL Sync

Real-time data synchronization is handled via Electric SQL, not the HTTP API.

GET /api/sync?query=<query_name>

This is used internally by the frontend for reactive data updates.

Error Handling

Error Response Format

{
  "errors": [
    {
      "message": "Error description",
      "field": "optional_field_name"
    }
  ]
}

Common Errors

Status	Description
401	Not authenticated
403	Permission denied
404	Resource not found
422	Validation error
500	Server error

Frontend SDK

The frontend uses generated TypeScript functions instead of raw HTTP calls:

import { create_task, list_tasks, move_task } from './lib/generated/ash'

// Create a task
const task = await create_task({
  title: 'New feature',
  column_id: columnId
})

// List tasks
const tasks = await list_tasks()

// Move task
await move_task({
  id: taskId,
  column_id: newColumnId
})

Regenerate the SDK with:

cd backend && mix ash.codegen