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

bash

GET /api/workspaces

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

Response

json

{
  "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

bash

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

bash

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

Field	Type	Required	Description
name	string	Yes	Workspace name
image	File	No	Workspace logo image

Update Workspace

Update an existing workspace. Requires Admin or Owner role.

Request

bash

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

bash

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

bash

GET /api/workspaces/:workspaceId/analytics

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

Response

json

{
  "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

bash

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)