# Nextcloud Capabilities Skill **Purpose:** Query Nextcloud server capabilities, version, and available apps. ## Overview This skill provides access to the Nextcloud Capabilities API (OCS endpoint). Capabilities are useful for: - Detecting server version - Checking which apps are installed - Validating feature availability before using app-specific APIs - Theming information (colors, logos) ## Prerequisites - Nextcloud server URL - Username and app token - HTTPS connection - OCS API enabled on Nextcloud ## Configuration Set these environment variables: ```bash export NEXTCLOUD_URL="https://cloud.example.com" export NEXTCLOUD_USER="your-username" export NEXTCLOUD_TOKEN="your-app-token" ``` Or create `~/.config/nextcloud/config.json`: ```json { "url": "https://cloud.example.com", "user": "your-username", "token": "your-app-token" } ``` ## Tool Reference ### `nextcloud-capabilities` - Get server capabilities ```bash # Get all capabilities nextcloud-capabilities # Get specific capability section nextcloud-capabilities --section core nextcloud-capabilities --section theming nextcloud-capabilities --section files nextcloud-capabilities --section deck ``` ### `nextcloud-version` - Get server version ```bash # Get full version info nextcloud-version # Get version only nextcloud-version --short ``` ### `nextcloud-apps` - List installed apps ```bash # List all apps nextcloud-apps # Filter by enabled state nextcloud-apps --enabled # Filter by name nextcloud-apps --search calendar ``` ### `nextcloud-theming` - Get theming information ```bash # Get all theming data nextcloud-theming # Get color scheme only nextcloud-theming --colors ``` ### `nextcloud-quota` - Get user quota information ```bash # Get quota (if files app provides) nextcloud-quota ``` ## API Details ### Capabilities Endpoint **URL:** `{NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities` **Method:** GET **Headers:** ``` OCS-APIRequest: true Accept: application/json Authorization: Basic {base64(user:token)} ``` **Response Format:** OCS XML with JSON data inside: ```xml ok 200 OK ``` ## Capability Sections ### Core Capabilities ```json { "core": { "pollinterval": 60, "webdav-root": "remote.php/webdav", "referenceapi": "https://github.com/nextcloud/server" } } ``` ### Theming Capabilities ```json { "theming": { "name": "Nextcloud", "url": "https://nextcloud.com", "slogan": "A safe home for all your data", "color": "#0082c9", "color-text": "#ffffff", "color-element": "#0082c9", "color-element-bright": "#aaaaaa", "color-element-dark": "#555555", "logo": "https://cloud.example.com/index.php/apps/theming/logo?v=1", "background": "https://cloud.example.com/index.php/apps/theming/background?v=1", "background-plain": "", "background-default": "" } } ``` ### Files Capabilities ```json { "files": { "versioning": true, "bigfilechunking": true, "undelete": true, "blacklisted_files": "", "direct_download": true, "direct_editing": true, "sharing": { "api_enabled": true, "public": { "enabled": true, "password": { "enforced": false, "enforced_for": {} }, "expire_date": { "enabled": true, "enforced": false, "days": "" }, "multiple": true, "upload": false }, "resharing": { "enabled": true, "upload": true } }, "federated_cloud_sharing": { "incoming": true, "outgoing": false } } } ``` ### Deck Capabilities ```json { "deck": { "enabled": true, "version": "1.0.0", "board_limits": [], "max_upload_size": 10485760 "can_create_boards": true, "can_manage": true "file_attachments": true, "comments": true, "labels": true "archived_board_support": false "archived_cards_support": false, "card_attachments": true, "acl_support": true, "acl_shares": true, "default_permission": { "PERMISSION_READ": true, "PERMISSION_EDIT": true, "PERMISSION_MANAGE": false, "PERMISSION_SHARE": false }, "calendar": false "notifications": true "polling_interval": 60 "version_history": [ { "version": "1.0.0", "features": "board_limits, card_attachments, comments, labels" } ] } } ``` ### Talk Capabilities ```json { "spreed": { "enabled": true, "version": "19.0.0", "features": { "audio": true, "video": true, "chat": true, "guest-signaling": false, "rooms": { "allow_guests": false, "max_rooms": -1, "max_participants": -1 }, "recording": { "enabled": false, "group_only": false }, "breakout_rooms": false, "webinar": false, "signaling": { "mode": "internal", "version": "2", "support": [] } }, "rich_object_list": true, "rich_object_config": false, "rich_object_list_share": true, "edit_messages": true, "federation": false, "voice": { "bridge": false }, "notifications": { "version": "3", "notifications": true, "push": true, "sound": true }, "expiration": { "enabled": false, "hours": "" }, "circles": false, "mentions": false, "commands": false } } } ``` ### Notifications Capabilities ```json { "notifications": { "ocs-endpoints": { "list": "/ocs/v2.php/apps/notifications/api/v2/notifications", "get": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}", "delete": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}", "push": "/ocs/v2.php/apps/notifications/api/v2/push", "devices": "/ocs/v2.php/apps/notifications/api/v2/devices", "register": "/ocs/v2.php/apps/notifications/api/v2/devices", "delete-device": "/ocs/v2.php/apps/notifications/api/v2/devices/{id}" }, "features": { "notifications": true, "push": false, "sound": "", "admin-notifications": false } } } ``` ### Calendar Capabilities ```json { "calendar": { "installed": true, "version": "4.0.0", "features": { "birthday-calendar": false, "publishing": false, "rich-description": false, "alarm": true, "timezones": true, "caldav": true, "sharee": { "api_enabled": true }, "webcal": { "enabled": false } }, "versionhistory": [] } } ``` ### Contacts Capabilities ```json { "dav": { "contacts": { "enabled": true, "version": "6.0.0", "features": { "photo": false, "circles": false, "addressbooks": true, "version": "6.0.0" } } } } ``` ### Notes Capabilities ```json { "notes": { "installed": true, "version": "4.6.4", "features": { "version": "4.6.4", "api_version": "1.0", "files": false, "versioning": true, "markdown": false, "markdown_file_extension": "txt", "markdown_file_extension_is_customizable": false "description_max_length": null, "categories": false, "editable": true, "custom_properties": null } } } ``` ## Implementation Notes ### Authentication ```bash curl -u ${NEXTCLOUD_USER}:${NEXTCLOUD_TOKEN} \ -H "OCS-APIRequest: true" \ -H "Accept: application/json" \ ${NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities ``` ### Example Request ```bash curl -u ${USER}:${TOKEN} \ -H "OCS-APIRequest: true" \ -H "Accept: application/json" \ https://cloud.example.com/ocs/v1.php/cloud/capabilities ``` ### Example Response ```json { "ocs": { "meta": { "statuscode": 100, "status": "ok" }, "data": { "version": { "major": 25, "minor": 0, "micro": "2", "string": "25.0.2", "edition": "", "extendedSupport": "" }, "capabilities": { "core": { ... }, "theming": { ... }, "files": { ... }, "deck": { ... }, "spreed": { ... }, "notifications": { ... }, "calendar": { ... }, "dav": { ... }, "notes": { ... } } } } } ``` ## Use Cases ### 1. Validate Server Capabilities ```bash # Check if Deck is enabled if nextcloud-capabilities | jq -r '.capabilities.deck.enabled'; then echo "Deck is available" else echo "Deck not available" fi # Check Deck version nextcloud-capabilities | jq -r '.capabilities.deck.version.string' ``` ### 2. Check API Version ```bash # Get version VERSION=$(nextcloud-version | jq -r '.capabilities.version.string') # Check if minimum version is met if [ "$VERSION" \> "25.0.0" ]; then echo "Server meets minimum version requirement" else echo "Server too old" fi ``` ### 3. Validate Feature Support ```bash # Check if notifications push is enabled if nextcloud-capabilities | jq -r '.capabilities.notifications.features.push'; then echo "Push notifications supported" else echo "Push notifications not supported" fi # Check if direct download is available if nextcloud-capabilities | jq -r '.capabilities.files.sharing.direct_download'; then echo "Direct download feature available" else echo "Direct download not available" fi ``` ### 4. Get Theming Colors ```bash # Get color scheme nextcloud-theming # Parse colors (example output) COLOR=$(echo "$THEMING" | jq -r '.theming.color') TEXT_COLOR=$(echo "$THEMING" | jq -r '.theming.color_text') echo "Primary color: $COLOR" echo "Text color: $TEXT_COLOR" ``` ### 5. App Availability Check ```bash # Check which apps are installed APPS=$(nextcloud-apps) echo "Installed apps:" echo "$APPS" | jq -r '.data.capabilities | keys' # Check if specific app exists if echo "$APPS" | jq -r 'has("deck")'; then echo "Deck is installed" fi if echo "$APPS" | jq -r 'has("calendar")'; then echo "Calendar is installed" fi if echo "$APPS" | jq -r 'has("notes")'; then echo "Notes is installed" fi ``` ## Error Handling | HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Success | Parse capabilities XML/JSON | | 401 | Unauthorized | Check credentials | | 403 | Forbidden | Check permissions | | 404 | Not Found | API endpoint not available | | 500 | Server Error | Nextcloud server error | ## Testing ```bash # Test connection nextcloud-test --capabilities # Test capabilities retrieval nextcloud-test --capabilities-get # Test specific section nextcloud-test --capabilities --section deck # Test all sections nextcloud-test --capabilities --all ``` ## Dependencies - `curl` for HTTP requests - `jq` for JSON parsing (recommended) ## Best Practices 1. **Cache capabilities** - Capabilities rarely change, cache for 5-10 minutes 2. **Validate before use** - Check if app is enabled before using app-specific APIs 3. **Version compatibility** - Check server version before using features 4. **Handle errors gracefully** - If capabilities endpoint returns error, assume minimal feature set 5. **Theming** - Use theming colors to customize UI when applicable 6. **Group Limits** - Check group_limit in Deck capabilities before creating boards ## Future Enhancements - [ ] Capabilities change detection - [ ] App installation/removal tracking - [ ] Feature compatibility matrix - [ ] Automatic API version adaptation - [ ] Server health check integration ## Related Skills - **nextcloud-files** - For file operations (capabilities will inform approach) - **nextcloud-deck** - For Kanban boards (check Deck capabilities first) - **nextcloud-talk** - For chat/calls (check Talk capabilities first) - **nextcloud-calendar** - For calendar events (check Calendar capabilities first) - **nextcloud-notes** - For notes (check Notes capabilities first) --- *OCS API implementation for Nextcloud capabilities detection*