Skip to main content
The Forge API is a RESTful API that allows you to programmatically manage dashboards, widgets, settings, notifications, and connected accounts.

​
Base URL

All API requests are made to: 
http://localhost:3000/api
In production, replace with your deployed domain.

​
Authentication

All API endpoints require authentication using BetterAuth session cookies. See the Authentication page for details.

​
Response Format

All responses are returned in JSON format. Successful responses return the requested resource or array of resources: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Dashboard",
  "userId": "user123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

​
Error Handling

Errors are returned with appropriate HTTP status codes and error messages:
​
error
string
Description of what went wrong

​
Common Error Codes

Status CodeDescription
400Bad Request - Invalid request body or validation error
401Unauthorized - Missing or invalid authentication
403Forbidden - Authenticated but lacks permission
404Not Found - Resource does not exist
500Internal Server Error - Something went wrong on the server

​
Example Error Response

{
  "error": "Dashboard not found"
}

​
Data Types

​
UUID

Resource IDs use UUID v4 format: 
550e8400-e29b-41d4-a716-446655440000

​
Timestamps

All timestamps are in ISO 8601 format: 
2024-01-15T10:30:00.000Z

​
JSONB Config

Many resources include a config field that accepts arbitrary JSON objects for flexible configuration storage: 
{
  "config": {
    "theme": "dark",
    "customOption": "value"
  }
}

​
Rate Limiting

Currently, there are no rate limits enforced. This may change in future versions.

​
Available Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us