@hailer/mcp 0.0.5 → 0.1.0

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

@@ -1,301 +0,0 @@
-# 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