@hailer/mcp 0.0.1

package/.claude/skills/mcp-tools/references/api-endpoints.md

@@ -0,0 +1,499 @@
+# API Endpoints Reference
+
+Complete reference for all working Hailer API endpoints with exact request/response formats.
+
+## Authentication
+
+**All requests require**:
+- Header: `hlrkey: {auth_token}`
+- Content-Type: `application/json`
+
+## Request Format Convention
+
+Most endpoints expect a **JSON array** as the request body:
+
+```javascript
+body: JSON.stringify([arg1, arg2, arg3])
+```
+
+This is **NOT standard REST** - always use array format unless specified otherwise.
+
+---
+
+## Activity Endpoints
+
+### 1. List Activities (`POST /v3/activity/list`)
+
+List and filter activities in a workflow/phase with advanced query capabilities.
+
+**Request Format**:
+```javascript
+POST /v3/activity/list
+body: JSON.stringify([workflowFilter, requestOptions])
+```
+
+**Example Request**:
+```javascript
+[
+  {
+    processId: "68446dc05b30685f67c6fcd4", // workflow ID
+    phaseId: "6901ebb64fd57ff171f43338"    // optional phase ID
+  },
+  {
+    limit: 50,              // max results (default: 50)
+    page: 1,                // 1-based pagination (NOT 0-based!)
+    sortBy: "updated",      // updated | created | name | priority
+    sortOrder: "desc",      // asc | desc
+    returnFlat: true,       // use field.key instead of field._id
+    filters: {              // optional advanced filters
+      and: [
+        { "field-id-company": { equalTo: "company-id" } },
+        { "field-id-created": { between: ["1717200000000", "1719791999000"] } }
+      ]
+    }
+  }
+]
+```
+
+**Filter Operators**:
+- `textSearch` - Partial text search in field
+- `equalTo` / `notEqualTo` - Exact matching
+- `contains` - Partial text matching
+- `greaterThan` / `lessThan` / `greaterThanOrEqual` / `lessThanOrEqual` - Numeric comparisons
+- `between` - Range filter: `[start, end]` for dates/numbers
+
+**Combining Filters**:
+```javascript
+filters: {
+  and: [
+    { "field-id-1": { equalTo: "value" } },
+    { "field-id-2": { greaterThan: 100 } }
+  ]
+}
+
+// Or use 'or':
+filters: {
+  or: [
+    { "field-id-status": { equalTo: "active" } },
+    { "field-id-status": { equalTo: "pending" } }
+  ]
+}
+```
+
+**Response**:
+```javascript
+{
+  data: [
+    {
+      _id: "activity-id",
+      name: "Activity Title",
+      // With returnFlat: true
+      relatedTo: "other-activity-id",  // Uses field.key
+      company: "company-id",
+      // Without returnFlat
+      fields: {
+        "field-id": { value: "value" }
+      }
+    }
+  ],
+  totalCount: 123,
+  page: 1,
+  totalPages: 3
+}
+```
+
+---
+
+### 2. Create Activities (`POST /v3/activity/createMany`)
+
+Create one or more activities in a workflow.
+
+**Request Format**:
+```javascript
+POST /v3/activity/createMany
+body: JSON.stringify([workflowId, activityDataArray, options])
+```
+
+**Example Request**:
+```javascript
+[
+  "68446dc05b30685f67c6fcd4",  // workflowId
+  [
+    {
+      name: "New Task",
+      fields: {
+        relatedTo: "topic-activity-id",  // ActivityLink field
+        priority: "high",
+        dueDate: "2025-11-15"
+      }
+    },
+    {
+      name: "Another Task",
+      fields: { relatedTo: "topic-activity-id" }
+    }
+  ],
+  {
+    returnDocument: true,          // Return created activities
+    phaseId: "initial-phase-id"    // Optional: specific phase
+  }
+]
+```
+
+**Response**:
+```javascript
+{
+  success: true,
+  activities: [
+    {
+      _id: "new-activity-id",
+      name: "New Task",
+      fields: { ... }
+    }
+  ]
+}
+```
+
+---
+
+### 3. Update Activities (`POST /v3/activity/updateMany`)
+
+Update one or more existing activities.
+
+**Request Format**:
+```javascript
+POST /v3/activity/updateMany
+body: JSON.stringify([updatesArray, options])
+```
+
+**Example Request**:
+```javascript
+[
+  [
+    {
+      _id: "activity-id-1",
+      name: "Updated Title",              // Update name
+      fields: {
+        priority: "urgent",
+        relatedTo: "new-topic-id"
+      },
+      phaseId: "new-phase-id"            // Move to different phase
+    },
+    {
+      _id: "activity-id-2",
+      fields: { status: "completed" }
+    }
+  ],
+  {
+    // Optional batch options
+    phaseId: "batch-phase-id"  // Apply to all activities
+  }
+]
+```
+
+**Response**:
+```javascript
+{
+  success: true,
+  updated: 2
+}
+```
+
+---
+
+## Discussion Endpoints
+
+### 4. Fetch Latest Messages (`POST /v3/discussion/message/latest`)
+
+Fetch the most recent messages from a discussion (up to 50 messages - API limit).
+
+**Request Format**:
+```javascript
+POST /v3/discussion/message/latest
+body: JSON.stringify([discussionId, limit])
+```
+
+**Example Request**:
+```javascript
+[
+  "684be83f68e9345040ad02a3",  // discussionId
+  50                            // optional limit (default: 50, max: 50)
+]
+```
+
+**Response**:
+```javascript
+{
+  messages: [
+    {
+      _id: "message-id",
+      msg: "Message content",
+      user: {
+        _id: "user-id",
+        name: "User Name"
+      },
+      created: "2025-10-30T10:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### 5. Fetch Previous Messages (`POST /v3/discussion/message/previous`)
+
+Paginate through older messages using the oldest message ID.
+
+**Request Format**:
+```javascript
+POST /v3/discussion/message/previous
+body: JSON.stringify([oldestMessageId, limit])
+```
+
+**Example Request**:
+```javascript
+[
+  "message-id-from-previous-fetch",  // Use _id from last message
+  50                                  // optional limit
+]
+```
+
+**Pagination Pattern**:
+```javascript
+// 1. Fetch latest 50 messages
+const latest = await fetchLatest(discussionId);
+const oldestId = latest.messages[latest.messages.length - 1]._id;
+
+// 2. Fetch next 50 older messages
+const previous = await fetchPrevious(oldestId);
+const nextOldestId = previous.messages[previous.messages.length - 1]._id;
+
+// 3. Continue...
+```
+
+---
+
+### 6. Send Message (`POST /api/messenger/send`)
+
+Post a message to a discussion.
+
+**Request Format**:
+```javascript
+POST /api/messenger/send
+body: JSON.stringify([messageData, discussionId])
+```
+
+**Example Request**:
+```javascript
+[
+  {
+    msg: "Hello world!",           // Message text
+    // Optional fields:
+    replyTo: "message-id",         // Reply to specific message
+    mentions: ["user-id-1", "user-id-2"]  // @mention users
+  },
+  "684be83f68e9345040ad02a3"      // discussionId
+]
+```
+
+**Response**:
+```javascript
+{
+  success: true,
+  message: {
+    _id: "new-message-id",
+    msg: "Hello world!",
+    created: "2025-10-30T10:00:00Z"
+  }
+}
+```
+
+---
+
+## Workspace & Search Endpoints
+
+### 7. Workspace Initialization (`POST /v2/core/init`)
+
+Initialize workspace and fetch all initial data (networks, users, workflows, etc.).
+
+**Request Format**:
+```javascript
+POST /v2/core/init
+body: JSON.stringify([workspaceId])
+```
+
+**Example Request**:
+```javascript
+["68446c045b30685f67c6fc8c"]
+```
+
+**Response**:
+```javascript
+{
+  workspace: { ... },
+  networks: [{ processes: [...], users: [...] }],
+  user: { ... }
+}
+```
+
+---
+
+### 8. Global Search (`POST /v2/search/global`)
+
+Search across activities, users, and other entities.
+
+**Request Format**:
+```javascript
+POST /v2/search/global
+body: JSON.stringify([searchOptions])
+```
+
+**Example Request**:
+```javascript
+[
+  {
+    search: "query string",
+    sections: ["activities", "users"],  // What to search
+    limit: 20
+  }
+]
+```
+
+**Response**:
+```javascript
+{
+  activities: [...],
+  users: [...]
+}
+```
+
+---
+
+## Socket.io Methods
+
+These use socket.io via `@hailer/cli`, not HTTP requests.
+
+### 9. Follow/Unfollow Activity (`activities.follow`)
+
+Join or leave an activity's discussion by following/unfollowing it.
+
+**Usage**:
+```typescript
+await client.socket.call('activities.follow', {
+  activityId: "activity-id",
+  follow: true  // true to join, false to leave
+});
+```
+
+**Behavior**:
+- Following an activity automatically joins its discussion
+- Unfollowing leaves the discussion
+- Toggles follow state
+
+---
+
+### 10. Leave Discussion (`messenger.leave_discussion`)
+
+Leave any discussion directly (not activity-specific).
+
+**Usage**:
+```typescript
+await client.socket.call('messenger.leave_discussion', {
+  discussionId: "discussion-id"
+});
+```
+
+---
+
+## Implementation Pattern
+
+When adding a new API endpoint:
+
+1. **Add function to `hailer-api.ts`**:
+```typescript
+export async function myNewEndpoint(
+  client: HailerClient,
+  arg1: string,
+  options: any = {}
+): Promise<any> {
+  const response = await fetch(
+    `${client.baseUrl}/v3/my/endpoint`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'hlrkey': client.authToken
+      },
+      body: JSON.stringify([arg1, options])
+    }
+  );
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+```
+
+2. **Add tool to static tool class** (ReadTools, WriteTools, etc.)
+
+3. **Register in GlobalToolRegistry**
+
+4. **Test with debug endpoint** or Claude Code
+
+5. **Update tool description** with ✅ status
+
+---
+
+## Error Handling
+
+**Common HTTP Status Codes**:
+- `401` - Invalid or missing authentication
+- `403` - Insufficient permissions
+- `404` - Endpoint or resource not found
+- `422` - Validation error (check request format)
+- `500` - Server error
+
+**Error Response Format**:
+```javascript
+{
+  error: "Error message",
+  details: { ... }
+}
+```
+
+**Always wrap API calls in try/catch**:
+```typescript
+try {
+  const result = await apiFunction();
+  return formatSuccess(result);
+} catch (error) {
+  console.error('API error:', error);
+  return `Error: ${error.message}`;
+}
+```
+
+---
+
+## Testing Endpoints
+
+Use the MCP server's debug endpoint:
+
+```bash
+curl -X POST http://localhost:3030/api/debug/execute-tool \
+  -H "Content-Type: application/json" \
+  -d '{
+    "apiKey": "test-key",
+    "toolName": "list_activities",
+    "args": {
+      "workflowId": "68446dc05b30685f67c6fcd4",
+      "limit": 10
+    }
+  }'
+```
+
+Or use Claude Code with the MCP connection:
+```
+claude mcp
+# Then: list activities in workflow X
+```