# Concentriq API Endpoint Classification

**Analysis Date:** 2025-12-11
**Total Controllers Analyzed:** 28 (13 documented + 15 undocumented)
**Controllers for Client Library:** 26 (excluded 2 partner integrations)

## Classification Summary

### Include in Client Library (26 controllers)

#### ✅ Customer-Facing Features (10 controllers)
- **auth** - Authentication, password management, access tokens (exclude deprecated S3 signing)
- **savedSearches** - User saved search queries
- **modules** (V2) - Analysis module management
- **savedImageDisplaySettings** (V2) - Fluorescence display preferences
- **aiFacetSearch** - AI-powered natural language search
- **notifications** - User notification management
- **imageFluorescenceChannels** - Image fluorescence channel settings
- **collaboration** - Chat/messaging for repositories
- **images, folders, imageSets** (documented) - Core resource management
- **annotations, attachments** (documented) - Image annotations and files

#### 👔 Admin/Manager Features (5 controllers)
- **roles** - Organization role management (requires `canManageRoles`)
- **userGroups** (V2) - User group management (requires `canManageGroups`)
- **records** - Audit logs for compliance (requires `canRequestSystemAudit` or `canRequestRepositoryAudit`)
- **statistics** - Organization metrics and analytics (requires `canViewAllOrganizationUserContent`)
- **users, organizations** (documented) - User and org management

#### 📊 Standard Documented Features (11 controllers)
- **imageSetGroups** - Unordered image set collections
- **collaborators** - Share permission management
- **metadata** - Custom metadata fields and values
- **templates** - Metadata templates
- **workflows** - Workflow state machines
- **orders** - Slide order requests (recuts, stains)
- **analysis** - Analysis job management

### ❌ Exclude from Client Library (2 controllers)

#### 🔌 Partner Integrations
- **halo** - HALO desktop viewer integration (browser-based XML generation)
- **visiopharm** - Visiopharm analysis software integration (bidirectional XML/MLD)
- **docs** - API documentation endpoint (meta-information, not data operations)

## Key Decision Criteria

### ✅ Include When:
1. **User-scoped resources** - Users manage their own data (savedSearches, notifications, savedImageDisplaySettings)
2. **Resource-scoped permissions** - Permissions checked at resource level (canManageImages, canCollaborate)
3. **Admin features for customers** - Organizational administration is customer-facing (roles, userGroups, statistics)
4. **Feature flag gated** - Feature flags are deployment config, not security (aiFacetSearch)
5. **Compliance features** - Audit logs are legitimate customer requirements (records)

### ❌ Exclude When:
1. **Partner-specific integrations** - Desktop software integrations (HALO, Visiopharm)
2. **Browser-only workflows** - UNC path generation, XML file downloads
3. **Meta-endpoints** - Documentation serving, internal tooling
4. **Deprecated endpoints** - Marked `@apiDeprecated` (S3 multipart signing)

## Permission Model Analysis

### Public Endpoints (No Auth Required)
- `POST /api/auth/login`
- `POST /api/auth/user` (if `config.openRegistration.enabled`)
- `POST /api/auth/forgot-password`
- `POST /api/auth/forgot-password/verify-token`
- `POST /api/auth/forgot-password/reset-password`

### User-Level Permissions (Authenticated)
Most endpoints require authentication but use **resource-scoped permissions**:
- **Image-scoped**: `canManageImages`, `canManageAnnotations`, `canManageMetadataValues`
- **ImageSet-scoped**: `canModifyImageSet`, `canUpdateNavigation`, `canCollaborate`
- **User-scoped**: Users can only access their own savedSearches, notifications, savedImageDisplaySettings

### Organization-Level Permissions (Admin)
These require elevated permissions but are still customer-facing:
- `canManageRoles` - Role management
- `canManageGroups` - User group management
- `canRequestSystemAudit` - System-wide audit logs
- `canRequestRepositoryAudit` - Repository-specific audit logs
- `canViewAllOrganizationUserContent` - Organization statistics

## Implementation Recommendations

### 1. Authentication Module Priority
```python
# High Priority - Essential Auth
client.v1.auth.login(email, password)
client.v1.auth.logout()
client.v1.auth.get_current_user()
client.v1.auth.update_password(old, new)
client.v1.auth.create_access_token()

# Medium Priority - Account Management
client.v1.auth.signup(name, email, password)
client.v1.auth.forgot_password(email)
client.v1.auth.reset_password(token, new_password)
client.v1.auth.verify_email(token)
```

### 2. Core Resources (Already in OpenAPI)
```python
client.v1.images.list()
client.v1.image_sets.list()
client.v1.folders.list()
client.v1.annotations.list()
```

### 3. User Features
```python
client.v1.saved_searches.list()
client.v1.notifications.list()
client.v2.saved_display_settings.list()
client.v1.collaboration.get_messages(room_id)
```

### 4. Admin Features (Documented as Admin-Only)
```python
client.v1.roles.list()  # Read-only for all
client.v1.roles.create()  # Requires canManageRoles
client.v2.user_groups.list()  # Same-org users
client.v2.user_groups.create()  # Requires canManageGroups
client.v1.statistics.get_totals()  # Requires canViewAllOrganizationUserContent
client.v1.records.get_system_audit()  # Requires canRequestSystemAudit
```

### 5. Advanced Features
```python
client.v1.ai_facet_search.search(prompt)  # Feature flag gated
client.v1.fluorescence_channels.update(image_id, channel_index, settings)
```

## Documentation Strategy

### Client Library Documentation
Each endpoint should be documented with:
1. **Permission requirements** - What permissions/roles are needed
2. **Feature availability** - Feature flags, config requirements
3. **Access scope** - User-scoped, resource-scoped, or organization-scoped
4. **Admin-only markers** - Clear indication when admin permissions required

Example:
```python
def get_system_audit_logs(self, date_start=None, date_end=None):
    """Get system-wide audit logs.

    **Permission Required:** canRequestSystemAudit
    **Access Level:** Organization Administrator
    **Returns:** CSV format audit log

    This endpoint is for compliance and audit purposes. Regular users
    will receive a 403 Forbidden error.
    """
```

## V2 vs V1 API Strategy

### V2 API Controllers (3 total)
- `user-groups` - Admin user group management
- `modules` - Analysis module configuration
- `saved-image-display-settings` - User display preferences

**Recommendation:** Include all V2 endpoints. They use modern AbstractController pattern with better validation and OpenAPI spec generation.

### API Version Namespacing
```python
# V1 API (most features)
client.v1.auth.login()
client.v1.images.list()
client.v1.saved_searches.list()

# V2 API (newer features)
client.v2.user_groups.list()
client.v2.modules.list()
client.v2.saved_display_settings.list()

# V3 API (future - modern NestJS)
client.v3.auth.create_token()
```

## Excluded Endpoints Detail

### 1. HALO Integration
**Why Excluded:**
- Browser-based workflow (generates downloadable .sis XML file)
- UNC path generation for Windows file shares
- Desktop software integration, not API data access
- Requires special network configuration

### 2. Visiopharm Integration
**Why Excluded:**
- Bidirectional XML/MLD file exchange
- Desktop software callback endpoint
- Complex R*tree markup processing
- Partner-specific file formats

### 3. API Documentation Endpoint
**Why Excluded:**
- Meta-information about API itself
- Client library doesn't need to fetch its own docs
- Not a data operation
- Permission-gated (`canAccessApiDocumentation`)

## Next Steps

1. ✅ **Classification Complete** - All endpoints analyzed and classified
2. 🔄 **Create Filtered Schema** - Generate schemas.json with includeInClientLibrary flags
3. ⏭️ **Implement Pydantic Models** - Create models for included schemas only
4. ⏭️ **Implement API Clients** - Build resource clients following classification
5. ⏭️ **Document Permissions** - Add permission documentation to each method
