nextcloud-integration/skills/nextcloud-capabilities/SKILL.md

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:

export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USER="your-username"
export NEXTCLOUD_TOKEN="your-app-token"

Or create ~/.config/nextcloud/config.json:

{
  "url": "https://cloud.example.com",
  "user": "your-username",
  "token": "your-app-token"
}

Tool Reference

nextcloud-capabilities - Get server capabilities

# 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

# Get full version info
nextcloud-version

# Get version only
nextcloud-version --short

nextcloud-apps - List installed apps

# List all apps
nextcloud-apps

# Filter by enabled state
nextcloud-apps --enabled

# Filter by name
nextcloud-apps --search calendar

nextcloud-theming - Get theming information

# Get all theming data
nextcloud-theming

# Get color scheme only
nextcloud-theming --colors

nextcloud-quota - Get user quota information

# 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 version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>200</statuscode>
    <message>OK</message>
  </meta>
  <data>
    <!-- JSON data here -->
  </data>
</ocs>

Capability Sections

Core Capabilities

{
  "core": {
    "pollinterval": 60,
    "webdav-root": "remote.php/webdav",
    "referenceapi": "https://github.com/nextcloud/server"
  }
}

Theming Capabilities

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "dav": {
    "contacts": {
      "enabled": true,
      "version": "6.0.0",
      "features": {
        "photo": false,
        "circles": false,
        "addressbooks": true,
        "version": "6.0.0"
      }
    }
  }
}

Notes Capabilities

{
  "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

curl -u ${NEXTCLOUD_USER}:${NEXTCLOUD_TOKEN} \
  -H "OCS-APIRequest: true" \
  -H "Accept: application/json" \
  ${NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities

Example Request

curl -u ${USER}:${TOKEN} \
  -H "OCS-APIRequest: true" \
  -H "Accept: application/json" \
  https://cloud.example.com/ocs/v1.php/cloud/capabilities

Example Response

{
  "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

# 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

# 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

# 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

# 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

# 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

# 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