Fairlx Logo

Beta

REST API Overview

How programmatic access to Fairlx works, and the routes the web app uses.

Introduction

The Fairlx web app talks to one REST API. It follows RESTful conventions and returns JSON. These pages list its routes for workspaces, projects, work items, and more.

Note

There is no public REST API yet. The routes on these pages are the web app's own and may change.

Authentication

Programmatic access goes through the Fairlx MCP endpoint at https://app.fairlx.com/api/mcp. An admin creates an API token for it in the project's MCP integration. The REST routes the web app uses accept only a signed-in session and may change.

Warning

An MCP API token is shown once, when it is created. Keep it out of client-side code and public repositories.

Base URL

The web app's routes live under:

Base URL
https://app.fairlx.com/api

Common Endpoints

Here are some commonly used endpoints:

Workspaces

MethodEndpointDescription
GET/workspacesList all workspaces
POST/workspacesCreate a workspace
GET/workspaces/:idGet workspace details
PATCH/workspaces/:idUpdate a workspace
DELETE/workspaces/:idDelete a workspace

Projects

MethodEndpointDescription
GET/projects?workspaceId=:idList projects in workspace
POST/projectsCreate a project
GET/projects/:idGet project details

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

  • 200 OK — Request succeeded
  • 201 Created — Resource created successfully
  • 400 Bad Request — Invalid request parameters
  • 401 Unauthorized — Not signed in
  • 403 Forbidden — Insufficient permissions
  • 404 Not Found — Resource not found
  • 429 Too Many Requests — Rate limit exceeded
  • 500 Internal Server Error — Server error

Error responses include a JSON body. Most carry a message in error, and some add a machine-readable code:

Error Response
{
  "error": "Unauthorized"
}
Error Response with a Code
{
  "error": "...",
  "code": "PLAN_PLUS_REQUIRED"
}

A request that fails validation returns 400 with the validation issues:

Validation Error
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["name"],
        "message": "Required"
      }
    ]
  }
}