@hailer/mcp 0.0.1

package/.claude/skills/hailer-api/references/activities.md

@@ -0,0 +1,620 @@
+# Hailer Activities API
+
+## Overview
+
+Activities are the core unit of work in Hailer - tasks, projects, issues, requests, or any trackable work item. Activities support rich metadata, hierarchical relationships, workflows, files, comments, and custom fields.
+
+## Activity Object Structure
+
+```json
+{
+  "id": "act_123",
+  "title": "Implement new feature",
+  "description": "Detailed description of the task",
+  "status": "in_progress",
+  "priority": "high",
+  "workspace_id": "ws_456",
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-16T14:20:00Z",
+  "created_by": {
+    "id": "user_123",
+    "name": "Johan Rekna",
+    "email": "johan@rekna.fi"
+  },
+  "assigned_to": [
+    {
+      "id": "user_456",
+      "name": "Team Member"
+    }
+  ],
+  "due_date": "2025-01-30T23:59:59Z",
+  "completed_at": null,
+  "parent_id": "act_100",
+  "tags": ["feature", "sprint-5"],
+  "custom_fields": {
+    "story_points": 8,
+    "customer": "Acme Corp"
+  },
+  "file_count": 3,
+  "comment_count": 12
+}
+```
+
+## Endpoints
+
+### List Activities
+
+```http
+GET /v3/activities
+```
+
+**Query Parameters:**
+- `workspace_id` - Filter by workspace
+- `status` - Filter by status
+- `priority` - Filter by priority
+- `assigned_to` - Filter by assigned user ID
+- `created_after` - ISO 8601 timestamp
+- `created_before` - ISO 8601 timestamp
+- `due_after` - ISO 8601 timestamp
+- `due_before` - ISO 8601 timestamp
+- `tags` - Comma-separated tags
+- `parent_id` - Filter by parent activity
+- `search` - Text search in title/description
+- `page` - Page number (default: 1)
+- `per_page` - Items per page (default: 50, max: 100)
+- `sort` - Sort field (e.g., `-created_at`, `due_date`, `priority`)
+
+**Example:**
+```http
+GET /v3/activities?workspace_id=ws_123&status=open&priority=high&sort=-created_at
+```
+
+**Response:**
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "per_page": 50,
+    "total": 150,
+    "total_pages": 3
+  }
+}
+```
+
+### Get Activity
+
+```http
+GET /v3/activities/{activity_id}
+```
+
+Returns full activity details including all custom fields, relationships, and metadata.
+
+### Create Activity
+
+```http
+POST /v3/activities
+Content-Type: application/json
+
+{
+  "title": "New feature request",
+  "workspace_id": "ws_123",
+  "description": "Detailed description",
+  "status": "open",
+  "priority": "medium",
+  "assigned_to": ["user_456", "user_789"],
+  "due_date": "2025-02-01T23:59:59Z",
+  "parent_id": "act_100",
+  "tags": ["feature", "customer-request"],
+  "custom_fields": {
+    "customer_name": "Acme Corp",
+    "estimated_hours": 40
+  }
+}
+```
+
+**Required Fields:**
+- `title` - Activity title (1-500 chars)
+- `workspace_id` - Target workspace
+
+**Response:** Full activity object with generated ID
+
+### Update Activity
+
+```http
+PATCH /v3/activities/{activity_id}
+Content-Type: application/json
+
+{
+  "status": "in_progress",
+  "assigned_to": ["user_123"],
+  "priority": "high"
+}
+```
+
+Only include fields you want to update. Omitted fields remain unchanged.
+
+### Delete Activity
+
+```http
+DELETE /v3/activities/{activity_id}
+```
+
+⚠️ **Warning:** This also deletes all comments, file associations, and child activities.
+
+**Response:** `204 No Content`
+
+## Batch Operations
+
+### Batch Create
+
+```http
+POST /v3/activities/batch
+Content-Type: application/json
+
+{
+  "activities": [
+    {
+      "title": "Task 1",
+      "workspace_id": "ws_123",
+      "status": "open"
+    },
+    {
+      "title": "Task 2",
+      "workspace_id": "ws_123",
+      "status": "open"
+    }
+  ]
+}
+```
+
+**Limits:** Up to 100 activities per batch
+
+**Response:**
+```json
+{
+  "created": 2,
+  "failed": 0,
+  "activities": [
+    {
+      "id": "act_124",
+      "title": "Task 1",
+      "success": true
+    },
+    {
+      "id": "act_125",
+      "title": "Task 2",
+      "success": true
+    }
+  ]
+}
+```
+
+### Batch Update
+
+```http
+PATCH /v3/activities/batch
+Content-Type: application/json
+
+{
+  "activities": [
+    {
+      "id": "act_123",
+      "status": "completed"
+    },
+    {
+      "id": "act_124",
+      "status": "in_progress",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+### Batch Delete
+
+```http
+DELETE /v3/activities/batch
+Content-Type: application/json
+
+{
+  "activity_ids": ["act_123", "act_124", "act_125"]
+}
+```
+
+## Activity Status
+
+### Standard Statuses
+
+- `open` - New or unstarted
+- `in_progress` - Currently being worked on
+- `blocked` - Cannot proceed due to dependency
+- `review` - Awaiting review/approval
+- `completed` - Successfully finished
+- `cancelled` - Abandoned or no longer needed
+
+### Custom Statuses
+
+Workspaces can define custom statuses:
+
+```http
+POST /v3/workspaces/{workspace_id}/statuses
+{
+  "name": "Testing",
+  "color": "#FF9800",
+  "order": 3
+}
+```
+
+## Activity Priority
+
+Standard priorities:
+- `critical` - Highest priority
+- `high` - Important
+- `medium` - Normal priority (default)
+- `low` - Can wait
+- `none` - No priority set
+
+## Comments
+
+### Add Comment
+
+```http
+POST /v3/activities/{activity_id}/comments
+Content-Type: application/json
+
+{
+  "text": "This is a comment",
+  "mentions": ["user_456"]
+}
+```
+
+Supports Markdown formatting.
+
+### List Comments
+
+```http
+GET /v3/activities/{activity_id}/comments?page=1&per_page=50
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "comment_789",
+      "text": "This is a comment",
+      "created_at": "2025-01-15T10:30:00Z",
+      "created_by": {
+        "id": "user_123",
+        "name": "Johan Rekna"
+      },
+      "mentions": [
+        {
+          "id": "user_456",
+          "name": "Team Member"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Update Comment
+
+```http
+PATCH /v3/activities/{activity_id}/comments/{comment_id}
+{
+  "text": "Updated comment text"
+}
+```
+
+### Delete Comment
+
+```http
+DELETE /v3/activities/{activity_id}/comments/{comment_id}
+```
+
+## Activity Relationships
+
+### Parent-Child Hierarchy
+
+Activities can be organized hierarchically:
+
+```python
+# Create parent project
+project = client.create_activity(
+    title="Website Redesign",
+    workspace_id="ws_123"
+)
+
+# Create child tasks
+task1 = client.create_activity(
+    title="Design mockups",
+    workspace_id="ws_123",
+    parent_id=project["id"]
+)
+
+task2 = client.create_activity(
+    title="Implement frontend",
+    workspace_id="ws_123",
+    parent_id=project["id"]
+)
+```
+
+### Get Child Activities
+
+```http
+GET /v3/activities?parent_id=act_123
+```
+
+### Activity Links
+
+Link related activities:
+
+```http
+POST /v3/activities/{activity_id}/links
+{
+  "linked_activity_id": "act_456",
+  "link_type": "blocks"
+}
+```
+
+**Link Types:**
+- `blocks` - This activity blocks another
+- `blocked_by` - This activity is blocked by another
+- `relates_to` - General relationship
+- `duplicates` - Duplicate activity
+- `parent_of` / `child_of` - Hierarchical
+
+### List Links
+
+```http
+GET /v3/activities/{activity_id}/links
+```
+
+## Assignments
+
+### Assign Users
+
+```http
+POST /v3/activities/{activity_id}/assignments
+{
+  "user_ids": ["user_123", "user_456"]
+}
+```
+
+This adds to existing assignments.
+
+### Replace Assignments
+
+```http
+PUT /v3/activities/{activity_id}/assignments
+{
+  "user_ids": ["user_789"]
+}
+```
+
+This replaces all assignments.
+
+### Assign Team
+
+```http
+POST /v3/activities/{activity_id}/assignments
+{
+  "team_id": "team_123"
+}
+```
+
+## Custom Fields
+
+### Define Custom Fields
+
+```http
+POST /v3/workspaces/{workspace_id}/custom-fields
+{
+  "name": "story_points",
+  "type": "number",
+  "label": "Story Points",
+  "required": false,
+  "options": null
+}
+```
+
+**Field Types:**
+- `text` - String values
+- `number` - Numeric values
+- `date` - Date only
+- `datetime` - Date and time
+- `boolean` - True/false
+- `select` - Single choice from options
+- `multiselect` - Multiple choices
+- `user` - User reference
+- `url` - URL field
+
+### Set Custom Field Values
+
+```http
+PATCH /v3/activities/{activity_id}
+{
+  "custom_fields": {
+    "story_points": 8,
+    "customer_name": "Acme Corp",
+    "delivery_date": "2025-02-15"
+  }
+}
+```
+
+## Activity Templates
+
+### Create from Template
+
+```http
+POST /v3/activities/from-template
+{
+  "template_id": "tmpl_123",
+  "workspace_id": "ws_456",
+  "variables": {
+    "project_name": "New Project",
+    "start_date": "2025-02-01"
+  }
+}
+```
+
+Templates can include predefined:
+- Title and description with variables
+- Status and priority
+- Custom fields
+- Subtasks
+- Checklists
+
+## Time Tracking
+
+### Log Time
+
+```http
+POST /v3/activities/{activity_id}/time-entries
+{
+  "hours": 4.5,
+  "description": "Frontend implementation",
+  "date": "2025-01-15"
+}
+```
+
+### Get Time Entries
+
+```http
+GET /v3/activities/{activity_id}/time-entries
+```
+
+### Time Statistics
+
+```http
+GET /v3/activities/{activity_id}/time-stats
+```
+
+**Response:**
+```json
+{
+  "total_hours": 42.5,
+  "estimated_hours": 40,
+  "remaining_hours": -2.5,
+  "entries_count": 12
+}
+```
+
+## Watchers/Followers
+
+### Add Watcher
+
+```http
+POST /v3/activities/{activity_id}/watchers
+{
+  "user_id": "user_123"
+}
+```
+
+### Remove Watcher
+
+```http
+DELETE /v3/activities/{activity_id}/watchers/{user_id}
+```
+
+### List Watchers
+
+```http
+GET /v3/activities/{activity_id}/watchers
+```
+
+## Activity History
+
+### Get Activity History
+
+```http
+GET /v3/activities/{activity_id}/history
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "hist_123",
+      "action": "updated",
+      "changes": {
+        "status": {
+          "old": "open",
+          "new": "in_progress"
+        },
+        "assigned_to": {
+          "added": ["user_456"],
+          "removed": []
+        }
+      },
+      "user": {
+        "id": "user_123",
+        "name": "Johan Rekna"
+      },
+      "timestamp": "2025-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+## Filters and Saved Views
+
+### Save Filter
+
+```http
+POST /v3/activities/filters
+{
+  "name": "My High Priority Tasks",
+  "workspace_id": "ws_123",
+  "filters": {
+    "status": ["open", "in_progress"],
+    "priority": ["high", "critical"],
+    "assigned_to": "user_123"
+  },
+  "sort": "-priority,due_date"
+}
+```
+
+### List Saved Filters
+
+```http
+GET /v3/activities/filters?workspace_id=ws_123
+```
+
+### Apply Filter
+
+```http
+GET /v3/activities?filter_id=filter_123
+```
+
+## Bulk Export
+
+### Export Activities
+
+```http
+GET /v3/activities/export?workspace_id=ws_123&format=csv
+GET /v3/activities/export?workspace_id=ws_123&format=json
+GET /v3/activities/export?workspace_id=ws_123&format=xlsx
+```
+
+Exports can include filters:
+```http
+GET /v3/activities/export?workspace_id=ws_123&status=completed&format=xlsx
+```
+
+## Best Practices
+
+1. **Use batch operations** - More efficient for bulk updates
+2. **Set appropriate due dates** - Helps with prioritization
+3. **Use tags consistently** - Makes filtering and reporting easier
+4. **Link related activities** - Provides context and dependencies
+5. **Add detailed descriptions** - Use Markdown for formatting
+6. **Track time accurately** - Essential for project estimation
+7. **Clean up completed activities** - Archive or delete old items
+8. **Use custom fields sparingly** - Too many can be overwhelming
+9. **Leverage templates** - For recurring activity types
+10. **Monitor activity history** - Track changes and accountability