agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/nextcloud/nextcloud-api/SKILL.md

nextcloud-api

Skill4 starsChanged 5 months agoMITView on GitHub

Use when managing Nextcloud users, groups, and apps via the Provisioning API (OCS). Covers user CRUD, group management, app enable/disable, and curl examples. NOT for Helm deployment — use nextcloud-helm.

  • Sends data out

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Does not delete users in the group.

    line 221

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Nextcloud Provisioning API

Overview

The Provisioning API enables external systems to create, edit, delete and query user attributes, manage groups, set quotas, query storage, and manage apps. Enabled by default. Uses the OCS API endpoint format.

Base URL: https://nextcloud.example.com/ocs/v1.php/cloud

Auth: Basic HTTP Auth (admin username:password) + OCS-APIRequest header

Headers (required for ALL calls):

  • Authorization: Basic <base64(admin:password)>
  • OCS-APIRequest: true
  • POST requests also require Content-Type: application/x-www-form-urlencoded

Output format: XML by default. Append ?format=json for JSON.

Users

Add a New User

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "userid=newuser" \
  -d "password=SecurePass123!" \
  -d "displayName=New User" \
  -d "email=newuser@example.com" \
  -d "groups[]=admin" \
  -d "groups[]=group1" \
  -d "quota=10GB"

Status codes: 100=ok, 101=invalid, 102=already exists, 104=group missing

List Users

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users?search=filter&limit=100&offset=0" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" | python3 -c "import sys, xml.etree.ElementTree as ET; print('\n'.join(e.text for e in ET.parse(sys.stdin).findall('.//users/element')))"

Get Single User

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" | python3 -c "
import sys, xml.etree.ElementTree as ET
root = ET.parse(sys.stdin).find('.//data')
for child in root:
    if child.tag == 'groups':
        print(f'{child.tag}: {[e.text for e in child]}')
    elif child.text and child.text.strip():
        print(f'{child.tag}: {child.text.strip()}')
"

Returns: enabled, id, quota, email, displayname, phone, address, website, twitter, groups.

Edit User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=email" \
  -d "value=newemail@example.com"

Editable fields: email, quota, displayname, phone, address, website, twitter, password. Admin can set quota; users can only edit their own email, displayname, password.

Disable User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/disable" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Enable User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/enable" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Delete User

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Get User Groups

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Add User to Group

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Remove User from Group

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Promote to Subadmin

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=group"

Demote from Subadmin

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=oldgroup"

Resend Welcome Email

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/welcome" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Groups

List Groups

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups?search=adm&limit=50&offset=0" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Create Group

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Status codes: 100=ok, 101=invalid, 102=already exists

Get Group Members

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups/admin" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Returns list of users in the group.

Get Group Subadmins

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Edit Group Display Name

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=displayname" \
  -d "value=My Group Name"

Delete Group

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Does not delete users in the group. Cannot delete the admin group.

Apps

List Apps

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/apps?filter=enabled" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Filter: enabled, disabled, or omit for all.

Get App Info

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Enable App

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files_texteditor" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Disable App

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files_texteditor" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Editable Fields Reference

Available via API:

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/user/fields" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Returns: displayname, email, phone, address, website, twitter.

Error Handling

Status CodeMeaning
100Success
101Invalid argument / failure
102Already exists (user/group)
103Cannot create sub-admins for admin group
104Group does not exist (user add) / insufficient privileges (user add to group)
105Failed to add user to group
106No group specified (required for sub-admins)
107Password policy violation
108Email required for password link
112Password change not supported by backend
113Editing field not allowed or doesn't exist

Common Mistakes

  • Missing OCS-APIRequest header — Every request needs OCS-APIRequest: true. Without it, requests return empty responses or 404.
  • Wrong base path — Use ocs/v1.php/cloud/, not ocs/v2.php/. The v2 path is for the Share API, not Provisioning.
  • Password with welcome email — Creating a user without a password AND without an email sends no welcome email. Always provide email when omitting password.
  • XML vs JSON — Default output is XML. For machine parsing, always append ?format=json. Python XML parsing of Nextcloud responses can fail on missing tags.
  • Group deletion — Deleting a group does not delete its users. Users remain ungrouped.
  • Cannot delete admin group — The admin group is protected. You cannot remove users from it via API.
  • POST needs form-urlencoded — POST/PUT requests must use Content-Type: application/x-www-form-urlencoded. JSON body is not accepted by the OCS API.
  • Quota format — unlimited works but 0 does not mean unlimited. Use -3 (negative bytes) for unlimited in the API field.

Tips

  • JSON output — Append ?format=json to any endpoint URL for JSON responses instead of XML
  • OCS-APIRequest header is mandatory — Without it, requests return empty or 404
  • Base URL path — ocs/v1.php/cloud/ (not ocs/v2.php/ — that's the Share API)
  • Password-on-create — Leave password empty and provide email to send welcome email with password setup link
  • Groups array — Use groups[]=group1 & groups[]=group2 for multiple groups in create
  • Quota format — Supports values like 1GB, 500MB, unlimited (or just enter none for unlimited)
  • Basic auth — Use the Nextcloud admin user, not an OCC system user
  • OCC alternative — For bulk operations or complex config, occ command inside the pod is more powerful:
    kubectl exec deploy/nextcloud -- php occ user:list
    kubectl exec deploy/nextcloud -- php occ group:add mygroup
    kubectl exec deploy/nextcloud -- php occ user:add --display-name="Layla Smith" --group="users" layla
  • App IDs — App ID for the Provisioning API is provisioning_api (enabled by default); remove it to disable the API
  • Rate limiting — Nextcloud has no built-in API rate limiting. Add at reverse proxy if needed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.