API Reference

LeanCore exposes a comprehensive REST API with 80+ endpoints across 40 controllers. All endpoints require JWT authentication unless noted as public.

Authentication

Login

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

{
  "email": "user@example.com",
  "password": "your-password"
}

Returns an accessToken for subsequent API calls.

Using the Token

Authorization: Bearer <accessToken>

Include the Authorization header on all authenticated requests.

Organization Context

X-Org-Id: <organization-uuid>

Many endpoints require the X-Org-Id header to scope the request to a specific organization.

Endpoint Groups

Authentication (3 endpoints)

Method	Path	Description
POST	/auth/login	Authenticate and get JWT
POST	/auth/refresh	Refresh an expiring token
GET	/auth/verify	Verify token validity

Registration (1 endpoint)

Method	Path	Description
POST	/register	Public -- create organization + admin user

Organizations (4 endpoints)

Method	Path	Description
GET	/orgs	List all organizations
GET	/orgs/{id}	Get organization details
PUT	/orgs/{id}	Update organization
PATCH	/orgs/{id}/billing-email	Update billing email

Users (6 endpoints)

Method	Path	Description
GET	/users/me	Get current user
GET	/users	List users in organization
POST	/users/invite	Invite a new user
PUT	/users/{id}	Update user
DELETE	/users/{id}	Remove user
PATCH	/users/{id}/role	Change user role

Specialists (6 endpoints)

Method	Path	Description
GET	/specialists	List specialists (paginated)
POST	/specialists	Create specialist
GET	/specialists/{id}	Get specialist details
PUT	/specialists/{id}	Update specialist
DELETE	/specialists/{id}	Remove specialist
POST	/specialists/wizard	AI-assisted specialist creation

Chat (5 endpoints)

Method	Path	Description
POST	/api/chat/stream	Send message (streaming response)
POST	/api/chat/async	Send message (async)
GET	/api/chat/sessions	List chat sessions
GET	/api/chat/sessions/{id}	Get session messages
POST	/api/chat/upload	Upload file to chat

MCP Integration (7 endpoints)

Method	Path	Description
GET	/orgs/{orgId}/mcps	List connected systems
POST	/orgs/{orgId}/mcps	Connect a system
PUT	/orgs/{orgId}/mcps/{id}	Update connection
DELETE	/orgs/{orgId}/mcps/{id}	Disconnect system
POST	/orgs/{orgId}/mcps/{id}/sync	Sync tools
GET	/orgs/{orgId}/mcps/{id}/tools	List available tools
GET	/mcp/catalog	Browse system catalog

Billing (10 endpoints)

Method	Path	Description
GET	/billing/credits/balance	Get current balance
GET	/billing/credits/usage	Get usage history
GET	/billing/model-rates	Get AI model pricing
GET	/billing/packages	List available packages
POST	/billing/credits/grant	Add credits
GET	/billing/capacity	Get capacity overview
GET	/billing/alerts	Get budget alerts
POST	/billing/alerts/acknowledge	Acknowledge an alert
GET	/billing/circuit	Get circuit breaker status
POST	/billing/circuit/toggle	Toggle circuit breaker

Workspaces (10 endpoints)

Method	Path	Description
GET	/workspaces	List workspaces
POST	/workspaces	Create workspace
GET	/workspaces/{id}	Get workspace
PUT	/workspaces/{id}	Update workspace
DELETE	/workspaces/{id}	Delete workspace
GET	/workspaces/{id}/threads	List threads
GET	/workspaces/{id}/artifacts	List artifacts
POST	/workspaces/{id}/files	Upload file
GET	/workspaces/{id}/files	List files
DELETE	/workspaces/{id}/files/{fileId}	Delete file

Tasks & Projects (4 endpoints)

Method	Path	Description
GET	/projects	List projects
POST	/projects	Create project
GET	/tasks	List tasks
POST	/tasks	Create task

Response Format

All API responses use standard HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Bad request (validation error)
401	Unauthorized (missing/invalid token)
402	Payment required (budget exhausted)
403	Forbidden (insufficient role)
404	Not found
500	Internal server error