@hailer/mcp 0.0.6 → 0.1.1

package/.claude/skills/hailer-api/references/workspaces-users.md

@@ -1,445 +0,0 @@
-# Hailer Workspaces & Users API
-
-## Workspaces
-
-Workspaces are top-level organizational units containing activities, datasets, files, and users.
-
-### Get Workspace
-
-```http
-GET /v3/workspaces/{workspace_id}
-```
-
-**Response:**
-```json
-{
-  "id": "ws_123",
-  "name": "Rekna Production",
-  "description": "Main workspace for Rekna operations",
-  "created_at": "2024-01-01T00:00:00Z",
-  "settings": {
-    "timezone": "Europe/Helsinki",
-    "language": "fi",
-    "date_format": "DD.MM.YYYY"
-  },
-  "member_count": 25,
-  "activity_count": 1523
-}
-```
-
-### List Workspaces
-
-```http
-GET /v3/workspaces
-```
-
-Returns all workspaces the authenticated user has access to.
-
-### Create Workspace
-
-```http
-POST /v3/workspaces
-Content-Type: application/json
-
-{
-  "name": "New Project Workspace",
-  "description": "Workspace for new project",
-  "settings": {
-    "timezone": "Europe/Helsinki",
-    "language": "fi"
-  }
-}
-```
-
-### Update Workspace
-
-```http
-PATCH /v3/workspaces/{workspace_id}
-Content-Type: application/json
-
-{
-  "name": "Updated Workspace Name",
-  "description": "New description"
-}
-```
-
-### Delete Workspace
-
-```http
-DELETE /v3/workspaces/{workspace_id}
-```
-
-⚠️ **Warning:** Deletes all activities, datasets, files, and content within the workspace.
-
-## Workspace Settings
-
-### Update Settings
-
-```http
-PATCH /v3/workspaces/{workspace_id}/settings
-Content-Type: application/json
-
-{
-  "timezone": "Europe/Helsinki",
-  "language": "fi",
-  "date_format": "DD.MM.YYYY",
-  "time_format": "24h",
-  "first_day_of_week": 1,
-  "working_hours": {
-    "start": "08:00",
-    "end": "17:00"
-  }
-}
-```
-
-## Users
-
-### Get User Profile
-
-```http
-GET /v3/users/me
-```
-
-**Response:**
-```json
-{
-  "id": "user_123",
-  "name": "Johan Rekna",
-  "email": "johan@rekna.fi",
-  "avatar_url": "https://avatars.hailer.com/user_123",
-  "timezone": "Europe/Helsinki",
-  "language": "fi",
-  "created_at": "2023-01-01T00:00:00Z"
-}
-```
-
-### Update User Profile
-
-```http
-PATCH /v3/users/me
-Content-Type: application/json
-
-{
-  "name": "Johan Rekna",
-  "timezone": "Europe/Helsinki",
-  "language": "fi"
-}
-```
-
-### Get User by ID
-
-```http
-GET /v3/users/{user_id}
-```
-
-### List Users in Workspace
-
-```http
-GET /v3/workspaces/{workspace_id}/users
-```
-
-**Response:**
-```json
-{
-  "data": [
-    {
-      "id": "user_123",
-      "name": "Johan Rekna",
-      "email": "johan@rekna.fi",
-      "role": "admin",
-      "joined_at": "2023-01-01T00:00:00Z"
-    }
-  ]
-}
-```
-
-## Workspace Members
-
-### Add Member to Workspace
-
-```http
-POST /v3/workspaces/{workspace_id}/members
-Content-Type: application/json
-
-{
-  "email": "newuser@company.com",
-  "role": "member",
-  "send_invitation": true
-}
-```
-
-**Roles:**
-- `admin` - Full workspace control
-- `member` - Standard access
-- `guest` - Limited access (read-only to assigned activities)
-
-### Update Member Role
-
-```http
-PATCH /v3/workspaces/{workspace_id}/members/{user_id}
-Content-Type: application/json
-
-{
-  "role": "admin"
-}
-```
-
-### Remove Member
-
-```http
-DELETE /v3/workspaces/{workspace_id}/members/{user_id}
-```
-
-## Permissions System
-
-### Permission Levels
-
-Hailer uses role-based and object-based permissions:
-
-**Workspace Level:**
-- `admin` - Full control
-- `member` - Standard access
-- `guest` - Limited access
-
-**Activity Level:**
-- `owner` - Created the activity
-- `assigned` - Assigned to activity
-- `follower` - Following activity
-- `workspace_member` - Has workspace access
-
-**Dataset Level:**
-- `admin` - Full control
-- `editor` - Can modify records
-- `viewer` - Read-only
-
-### Check Permissions
-
-```http
-GET /v3/activities/{activity_id}/permissions/me
-```
-
-**Response:**
-```json
-{
-  "can_read": true,
-  "can_update": true,
-  "can_delete": false,
-  "can_assign": true,
-  "can_comment": true
-}
-```
-
-### List Activity Permissions
-
-```http
-GET /v3/activities/{activity_id}/permissions
-```
-
-**Response:**
-```json
-{
-  "data": [
-    {
-      "user_id": "user_123",
-      "name": "Johan Rekna",
-      "role": "owner",
-      "permissions": ["read", "update", "delete", "assign"]
-    },
-    {
-      "user_id": "user_456",
-      "name": "Team Member",
-      "role": "assigned",
-      "permissions": ["read", "update", "comment"]
-    }
-  ]
-}
-```
-
-### Set Activity Permissions
-
-```http
-POST /v3/activities/{activity_id}/permissions
-Content-Type: application/json
-
-{
-  "user_id": "user_456",
-  "role": "assigned"
-}
-```
-
-### Grant Workspace-Wide Permissions
-
-```http
-POST /v3/workspaces/{workspace_id}/permissions
-Content-Type: application/json
-
-{
-  "user_id": "user_456",
-  "permissions": {
-    "can_create_activities": true,
-    "can_create_datasets": false,
-    "can_manage_workflows": false
-  }
-}
-```
-
-## Teams
-
-Groups of users within a workspace.
-
-### Create Team
-
-```http
-POST /v3/workspaces/{workspace_id}/teams
-Content-Type: application/json
-
-{
-  "name": "Development Team",
-  "description": "Software development team",
-  "member_ids": ["user_123", "user_456"]
-}
-```
-
-### Add Users to Team
-
-```http
-POST /v3/teams/{team_id}/members
-Content-Type: application/json
-
-{
-  "user_ids": ["user_789"]
-}
-```
-
-### Assign Team to Activity
-
-```http
-POST /v3/activities/{activity_id}/assignments
-Content-Type: application/json
-
-{
-  "team_id": "team_123"
-}
-```
-
-## API Keys
-
-Create API keys for programmatic access:
-
-### Create API Key
-
-```http
-POST /v3/api-keys
-Content-Type: application/json
-
-{
-  "name": "Automation Script",
-  "workspace_id": "ws_123",
-  "scopes": ["activities:read", "activities:write", "datasets:read"],
-  "expires_at": "2026-12-31T23:59:59Z"
-}
-```
-
-**Response:**
-```json
-{
-  "id": "key_789",
-  "name": "Automation Script",
-  "key": "hsk_abc123def456...",
-  "scopes": ["activities:read", "activities:write", "datasets:read"],
-  "created_at": "2025-01-15T10:30:00Z",
-  "expires_at": "2026-12-31T23:59:59Z"
-}
-```
-
-⚠️ **Warning:** API key is only shown once. Store it securely.
-
-### List API Keys
-
-```http
-GET /v3/api-keys
-```
-
-### Revoke API Key
-
-```http
-DELETE /v3/api-keys/{key_id}
-```
-
-## Available Scopes
-
-### Activity Scopes
-- `activities:read` - Read activities
-- `activities:write` - Create/update activities
-- `activities:delete` - Delete activities
-
-### Dataset Scopes
-- `datasets:read` - Read datasets and records
-- `datasets:write` - Create/update datasets and records
-- `datasets:delete` - Delete datasets and records
-
-### File Scopes
-- `files:read` - Read files
-- `files:write` - Upload files
-- `files:delete` - Delete files
-
-### Workspace Scopes
-- `workspaces:read` - Read workspace information
-- `workspaces:write` - Update workspace settings
-- `workspaces:admin` - Full workspace administration
-
-### User Scopes
-- `users:read` - Read user information
-- `users:write` - Update user profiles
-
-## Audit Logs
-
-Track actions within workspace:
-
-### List Audit Logs
-
-```http
-GET /v3/workspaces/{workspace_id}/audit-logs
-```
-
-**Query Parameters:**
-- `user_id` - Filter by user
-- `action` - Filter by action type
-- `resource_type` - Filter by resource (activity, dataset, etc.)
-- `start_date` - ISO 8601 timestamp
-- `end_date` - ISO 8601 timestamp
-
-**Response:**
-```json
-{
-  "data": [
-    {
-      "id": "log_123",
-      "action": "activity.created",
-      "user": {
-        "id": "user_123",
-        "name": "Johan Rekna"
-      },
-      "resource": {
-        "type": "activity",
-        "id": "act_456"
-      },
-      "timestamp": "2025-01-15T10:30:00Z",
-      "metadata": {
-        "ip_address": "192.168.1.1",
-        "user_agent": "Mozilla/5.0..."
-      }
-    }
-  ]
-}
-```
-
-## Best Practices
-
-1. **Use teams for group permissions** - Easier than managing individual user permissions
-2. **Create API keys with minimal scopes** - Principle of least privilege
-3. **Rotate API keys regularly** - Set expiration dates
-4. **Monitor audit logs** - Track suspicious activity
-5. **Remove inactive members** - Clean up workspace regularly
-6. **Use guest role for external collaborators** - Limit access appropriately
-7. **Check permissions before operations** - Avoid unnecessary API calls