@hailer/mcp 0.0.1

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

@@ -0,0 +1,301 @@
+# Hailer Files API
+
+## Overview
+
+Hailer's Files API allows uploading, downloading, and managing files attached to activities, workspaces, and datasets.
+
+## Endpoints
+
+### Upload File
+
+```http
+POST /v3/files
+Content-Type: multipart/form-data
+
+file: (binary)
+activity_id: 123 (optional)
+workspace_id: ws_456 (optional)
+```
+
+**Python Example:**
+```python
+with open('document.pdf', 'rb') as f:
+    response = requests.post(
+        'https://api.hailer.local.gd/v3/files',
+        headers={'Authorization': f'Bearer {token}'},
+        files={'file': f},
+        data={'activity_id': '123'}
+    )
+```
+
+**Response:**
+```json
+{
+  "id": "file_789",
+  "filename": "document.pdf",
+  "size": 524288,
+  "mime_type": "application/pdf",
+  "url": "https://files.hailer.com/file_789",
+  "thumbnail_url": "https://files.hailer.com/file_789/thumb",
+  "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+### Get File Metadata
+
+```http
+GET /v3/files/{file_id}
+```
+
+**Response:**
+```json
+{
+  "id": "file_789",
+  "filename": "document.pdf",
+  "size": 524288,
+  "mime_type": "application/pdf",
+  "url": "https://files.hailer.com/file_789",
+  "created_at": "2025-01-15T10:30:00Z",
+  "created_by": {
+    "id": "user_123",
+    "name": "Johan Rekna"
+  },
+  "activity_id": "act_456",
+  "workspace_id": "ws_789"
+}
+```
+
+### Download File
+
+```http
+GET /v3/files/{file_id}/download
+```
+
+Returns file binary with appropriate Content-Type header.
+
+**Python Example:**
+```python
+response = requests.get(
+    f'https://api.hailer.local.gd/v3/files/{file_id}/download',
+    headers={'Authorization': f'Bearer {token}'},
+    stream=True
+)
+
+with open('downloaded_file.pdf', 'wb') as f:
+    for chunk in response.iter_content(chunk_size=8192):
+        f.write(chunk)
+```
+
+### Delete File
+
+```http
+DELETE /v3/files/{file_id}
+```
+
+**Response:** `204 No Content`
+
+### List Files
+
+```http
+GET /v3/files?activity_id=123
+GET /v3/files?workspace_id=ws_456
+```
+
+**Query Parameters:**
+- `activity_id` - Filter by activity
+- `workspace_id` - Filter by workspace
+- `created_after` - ISO 8601 timestamp
+- `created_before` - ISO 8601 timestamp
+- `mime_type` - Filter by MIME type
+- `page` - Page number
+- `per_page` - Items per page (max 100)
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": "file_789",
+      "filename": "document.pdf",
+      "size": 524288,
+      "mime_type": "application/pdf",
+      "url": "https://files.hailer.com/file_789",
+      "created_at": "2025-01-15T10:30:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "per_page": 50,
+    "total": 15
+  }
+}
+```
+
+### Update File Metadata
+
+```http
+PATCH /v3/files/{file_id}
+Content-Type: application/json
+
+{
+  "filename": "renamed_document.pdf"
+}
+```
+
+## Supported MIME Types
+
+### Documents
+- `application/pdf` - PDF documents
+- `application/msword` - Word (.doc)
+- `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - Word (.docx)
+- `application/vnd.ms-excel` - Excel (.xls)
+- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - Excel (.xlsx)
+- `text/plain` - Text files
+- `text/csv` - CSV files
+
+### Images
+- `image/jpeg` - JPEG images
+- `image/png` - PNG images
+- `image/gif` - GIF images
+- `image/svg+xml` - SVG images
+- `image/webp` - WebP images
+
+### Archives
+- `application/zip` - ZIP archives
+- `application/x-rar-compressed` - RAR archives
+
+### Other
+- `application/json` - JSON files
+- `application/xml` - XML files
+
+## File Size Limits
+
+- Maximum file size: 100 MB per file
+- Maximum total storage: Depends on workspace plan
+- Thumbnail generation: Automatic for images and PDFs
+
+## Thumbnails
+
+Hailer automatically generates thumbnails for:
+- Images (JPEG, PNG, GIF, WebP)
+- PDF documents (first page)
+
+Access thumbnails:
+```http
+GET /v3/files/{file_id}/thumbnail?size=small
+GET /v3/files/{file_id}/thumbnail?size=medium
+GET /v3/files/{file_id}/thumbnail?size=large
+```
+
+Sizes:
+- `small` - 150x150px
+- `medium` - 300x300px
+- `large` - 600x600px
+
+## Batch Upload
+
+```http
+POST /v3/files/batch
+Content-Type: multipart/form-data
+
+files[]: (binary) multiple files
+activity_id: 123
+```
+
+**Response:**
+```json
+{
+  "files": [
+    {
+      "id": "file_789",
+      "filename": "doc1.pdf",
+      "success": true
+    },
+    {
+      "filename": "doc2.pdf",
+      "success": false,
+      "error": "File too large"
+    }
+  ]
+}
+```
+
+## File Sharing
+
+### Generate Public Link
+
+```http
+POST /v3/files/{file_id}/share
+Content-Type: application/json
+
+{
+  "expires_at": "2025-12-31T23:59:59Z",
+  "password": "optional_password"
+}
+```
+
+**Response:**
+```json
+{
+  "share_url": "https://share.hailer.com/abc123def456",
+  "expires_at": "2025-12-31T23:59:59Z"
+}
+```
+
+### Revoke Public Link
+
+```http
+DELETE /v3/files/{file_id}/share
+```
+
+## File Permissions
+
+Files inherit permissions from their parent:
+- Activity files: Same permissions as activity
+- Workspace files: Same permissions as workspace
+
+Check file access:
+```http
+GET /v3/files/{file_id}/permissions
+```
+
+## Advanced: Direct Upload to S3
+
+For large files, use pre-signed S3 URLs:
+
+1. Request upload URL:
+```http
+POST /v3/files/upload-url
+{
+  "filename": "large_video.mp4",
+  "size": 52428800,
+  "mime_type": "video/mp4"
+}
+```
+
+2. Upload directly to S3:
+```python
+response = requests.put(
+    presigned_url,
+    data=open('large_video.mp4', 'rb'),
+    headers={'Content-Type': 'video/mp4'}
+)
+```
+
+3. Confirm upload:
+```http
+POST /v3/files/confirm
+{
+  "upload_id": "upload_123",
+  "activity_id": "act_456"
+}
+```
+
+## Best Practices
+
+1. **Use streaming for large files** - Don't load entire file into memory
+2. **Check file size before upload** - Validate against 100MB limit
+3. **Set appropriate MIME types** - For proper file handling
+4. **Use batch upload for multiple files** - More efficient than individual uploads
+5. **Clean up temporary files** - Delete files when no longer needed
+6. **Use thumbnails for previews** - Don't download full images for UI previews