Skip to main content

Workspace Services API (v1)

Overview​

The Workspace Services API allows workspace owners to manage workspace services that can be assigned to sessions. Each workspace can create, update, and delete services with properties like name, description, duration, price, color, and scope. Services are categorized by scope (currently: sessions) to define their usage within the workspace.

Method & Path​

All endpoints use the base path:

/api/v1/workspace/:workspaceId/services

Authentication​

Required: Workspace authentication via session cookie.

Headers​

  • Content-Type: application/json
  • Cookie with workspace session

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace ID

List Services​

Method & Path​

GET /api/v1/workspace/:workspaceId/services

Description​

Retrieves a list of all services for the workspace.

Query Parameters​

ParameterTypeRequiredDescription
isActivebooleanNoFilter by active status (true/false)
scopestringNoFilter by scope. Currently only sessions is supported

Response 200 OK​

{
  "services": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f191e810c19729de860ea",
      "name": "استشارة طبية",
      "description": "جلسة استشارة طبية شاملة",
      "durationMinutes": 60,
      "price": 150.00,
      "color": "#3B82F6",
      "scope": "sessions",
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Common Errors​

404 Not Found: Workspace not found or access denied 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired or insufficient permissions

Get Service by ID​

Method & Path​

GET /api/v1/workspace/:workspaceId/services/:serviceId

Description​

Retrieves a specific service by its ID.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace ID
serviceIdstringYesThe service ID

Response 200 OK​

{
  "service": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "استشارة طبية",
    "description": "جلسة استشارة طبية شاملة",
    "durationMinutes": 60,
    "price": 150.00,
    "color": "#3B82F6",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Common Errors​

404 Not Found: Service not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Create Service​

Method & Path​

POST /api/v1/workspace/:workspaceId/services

Description​

Creates a new service for the workspace.

Request Body​

{
  "name": "استشارة طبية",
  "description": "جلسة استشارة طبية شاملة",
  "durationMinutes": 60,
  "price": 150.00,
  "color": "#3B82F6",
  "scope": "sessions",
  "isActive": true
}

Fields:

  • name (string, required): Service name (1-200 characters)
  • description (string, optional): Service description (max 1000 characters)
  • durationMinutes (number, optional): Default duration in minutes (min: 1)
  • price (number, optional): Default price (min: 0)
  • color (string, optional): Hex color code for display (e.g., "#3B82F6")
  • scope (string, optional): Service scope. Currently only sessions is supported (default: "sessions")
  • isActive (boolean, optional): Whether the service is active (default: true)

Response 201 Created​

{
  "service": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "استشارة طبية",
    "description": "جلسة استشارة طبية شاملة",
    "durationMinutes": 60,
    "price": 150.00,
    "color": "#3B82F6",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Common Errors​

400 Bad Request: Invalid input data 409 Conflict: Service with this name already exists 404 Not Found: Workspace not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Update Service​

Method & Path​

PATCH /api/v1/workspace/:workspaceId/services/:serviceId

Description​

Updates an existing service.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace ID
serviceIdstringYesThe service ID

Request Body​

All fields are optional:

{
  "name": "استشارة طبية محدثة",
  "description": "وصف محدث",
  "durationMinutes": 90,
  "price": 200.00,
  "color": "#10B981",
  "scope": "sessions",
  "isActive": false
}

Response 200 OK​

{
  "service": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "استشارة طبية محدثة",
    "description": "وصف محدث",
    "durationMinutes": 90,
    "price": 200.00,
    "color": "#10B981",
    "isActive": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Common Errors​

400 Bad Request: Invalid input data 409 Conflict: Service with this name already exists 404 Not Found: Service not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Delete Service​

Method & Path​

DELETE /api/v1/workspace/:workspaceId/services/:serviceId

Description​

Deletes a service from the workspace.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace ID
serviceIdstringYesThe service ID

Response 204 No Content​

No response body.

Common Errors​

404 Not Found: Service not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Service Model​

Service Object​

{
  id: string;                    // Service ID
  workspaceId: string;          // Workspace ID
  name: string;                  // Service name (1-200 chars)
  description?: string;          // Service description (max 1000 chars)
  durationMinutes?: number;      // Default duration in minutes
  price?: number;                // Default price
  color?: string;                // Hex color code (e.g., "#3B82F6")
  scope: string;                 // Service scope (currently: "sessions")
  isActive: boolean;             // Active status
  createdAt: string;             // ISO datetime
  updatedAt: string;             // ISO datetime
}

Notes​

  • Service names must be unique within a workspace
  • Service colors must be unique within a workspace (cannot have two services with the same color)
  • Services can be marked as inactive without deletion
  • Color must be a valid hex color code (3 or 6 digits)
  • Duration and price are optional and can be set per session
  • Services are required when creating sessions (serviceIds array field)
  • Service colors are used to visually identify sessions in calendar views
  • Scope field: The scope field determines the purpose of the service. Currently, only sessions is supported, meaning the service is used for session/appointment management. This allows for future expansion to support services for other features (e.g., products, appointments, etc.)
  • Services with scope: "sessions" are automatically filtered in session-related queries and widgets