API Documentation

Technical reference for Resolflow REST API and WebSocket integration

Internal API Reference

This documentation describes Resolflow's internal REST API for understanding how the platform works. Resolflow is a self-contained application, not a platform API for third-party integrations. If you need to interact with Resolflow programmatically, use the MCP protocol instead.

API Overview

Architecture and capabilities

RESTful Design

Standard HTTP methods (GET, POST, PATCH, DELETE)

Real-time Updates

WebSocket for live notifications

JSON Responses

Consistent data format

Authentication

JWT-based authentication with dual tokens

Token System

Access Token
15 minutes

Short-lived token stored in HTTP-only cookie. Used for API requests.

Refresh Token
7 days

Long-lived token for obtaining new access tokens without re-login.

# Login to get tokens

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Response:
{
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

# Use access token in requests

GET /api/workspaces
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Core API Endpoints

Main resources and operations

Authentication

POST
/api/auth/register

Create new account

POST
/api/auth/login

Login with email/password

POST
/api/auth/refresh

Get new access token

POST
/api/auth/logout

Clear tokens and end session

GET
/api/auth/me

Get current user info

Workspaces

GET
/api/workspaces

List all workspaces

GET
/api/workspaces/:id

Get workspace details

POST
/api/workspaces

Create new workspace

PATCH
/api/workspaces/:id

Update workspace

DELETE
/api/workspaces/:id

Delete workspace

Projects

GET
/api/workspaces/:workspaceId/projects

List projects in workspace

POST
/api/workspaces/:workspaceId/projects

Create project

PATCH
/api/projects/:id

Update project settings

Tasks & Todos

GET
/api/projects/:projectId/tasks

List tasks

POST
/api/projects/:projectId/tasks

Create task

GET
/api/tasks/:taskId/todos

List todos for task

PATCH
/api/todos/:id

Update todo status

Agents & Connections

GET
/api/workspaces/:workspaceId/agents

List MCP agents

POST
/api/projects/:projectId/tokens

Generate MCP token

GET
/api/workspaces/:workspaceId/repos

List connected GitHub repos

Orchestrator

POST
/api/orchestrator/suggest-tasks

AI-powered task generation

GET
/api/orchestrator/inbox

Get orchestrator messages

POST
/api/orchestrator/ask

Ask orchestrator for guidance

Reports & Analytics

GET
/api/projects/:projectId/reports

List reports

GET
/api/reports/:id

Get report details

WebSocket Real-time Updates

Live notifications and data synchronization

Connect to WebSocket server for real-time updates on tasks, todos, orchestrator messages, and reports.

# Connect to WebSocket

// Send authentication
{
  "type": "auth",
  "token": "your-access-token"
}

// Subscribe to workspace updates
{
  "type": "subscribe",
  "workspaceId": "workspace-uuid"
}

// Receive updates
{
  "type": "task_updated",
  "data": {
    "taskId": "uuid",
    "status": "in_progress",
    "updatedBy": "agent-name"
  }
}

Event Types

task_created

New task added

task_updated

Task status changed

todo_updated

Todo progress update

orchestrator_message

New guidance from AI

report_generated

New analytics report

loop_signal

Agent stuck detected

Example: Create Task

Complete request and response flow

Request

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium"
}

Response (201 Created)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium",
  "status": "not_started",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "user-uuid",
  "createdAt": "2024-02-12T10:30:00Z",
  "updatedAt": "2024-02-12T10:30:00Z"
}

Rate Limits & Best Practices

Guidelines for API usage

Rate Limits

Currently no rate limits enforced for self-hosted instances. For production deployments, consider implementing rate limiting based on your infrastructure.

Best Practices

  • • Use WebSocket for real-time data instead of polling
  • • Cache responses client-side (React Query handles this)
  • • Batch operations when possible (bulk create todos)
  • • Handle token refresh automatically with interceptors
  • • Use optimistic updates for better UX

Error Handling

Standard HTTP status codes:

  • • 200 - Success
  • • 201 - Created
  • • 400 - Bad request (validation errors)
  • • 401 - Unauthorized (invalid/expired token)
  • • 403 - Forbidden (insufficient permissions)
  • • 404 - Not found
  • • 500 - Server error