Fairlx Logo

Beta

Get Started

Workspaces API

Create, manage, and collaborate on workspaces programmatically.

Overview

Workspaces are containers for related projects. The Workspaces API allows you to manage workspaces, invite members, and access workspace analytics.

Note

All workspace endpoints require authentication. Include your API key in the Authorization header.

List Workspaces

Retrieve all workspaces the authenticated user has access to.

Request
GET /api/workspaces

curl -X GET "https://api.fairlx.com/v1/workspaces" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": {
    "documents": [
      {
        "$id": "ws_abc123",
        "name": "Engineering",
        "imageUrl": "https://...",
        "inviteCode": "XY7K9M",
        "userId": "user_123",
        "organizationId": "org_456",
        "$createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "total": 1
  }
}

Get Workspace

Retrieve details for a specific workspace.

Request
GET /api/workspaces/:workspaceId

curl -X GET "https://api.fairlx.com/v1/workspaces/ws_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Workspace

Create a new workspace. Uses form data for file uploads.

Request
POST /api/workspaces
Content-Type: multipart/form-data

curl -X POST "https://api.fairlx.com/v1/workspaces" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Engineering" \
  -F "image=@/path/to/logo.png"

Request Body

FieldTypeRequiredDescription
namestringYesWorkspace name
imageFileNoWorkspace logo image

Update Workspace

Update an existing workspace. Requires Admin or Owner role.

Request
PATCH /api/workspaces/:workspaceId
Content-Type: multipart/form-data

curl -X PATCH "https://api.fairlx.com/v1/workspaces/ws_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Engineering Team"

Delete Workspace

Delete a workspace and all related data. Requires Owner role.

Warning

Deleting a workspace permanently removes all projects, tasks, time logs, and member associations. This action cannot be undone.
Request
DELETE /api/workspaces/:workspaceId

curl -X DELETE "https://api.fairlx.com/v1/workspaces/ws_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Workspace Analytics

Get task analytics for a workspace, including monthly comparisons.

Request
GET /api/workspaces/:workspaceId/analytics

curl -X GET "https://api.fairlx.com/v1/workspaces/ws_abc123/analytics" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": {
    "taskCount": 45,
    "taskDifference": 12,
    "assignedTaskCount": 15,
    "assignedTaskDifference": 3,
    "completedTaskCount": 28,
    "completedTaskDifference": 8,
    "incompleteTaskCount": 17,
    "incompleteTaskDifference": 4,
    "overdueTaskCount": 3,
    "overdueTaskDifference": -2
  }
}

Join Workspace

Join a workspace using an invite code.

Request
POST /api/workspaces/:workspaceId/join
Content-Type: application/json

curl -X POST "https://api.fairlx.com/v1/workspaces/ws_abc123/join" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "XY7K9M"}'

Additional Endpoints

  • POST /workspaces/:id/reset-invite-code — Reset the invite code (Admin/Owner)
  • GET /workspaces/:id/info — Get basic workspace info (public)