Nextcloud Syntax Webdav

nextcloud-syntax-webdav

Quick Reference

DAV Endpoint Structure

File Operations

Property Namespaces

Common Properties

Special Request Headers

Depth Header Values (PROPFIND)

Critical Warnings

NEVER omit the Destination header on MOVE or COPY requests -- the server returns 400 Bad Request.

NEVER use Depth: infinity on large directories -- the server may time out or reject the request. ALWAYS use Depth: 1 and paginate manually.

NEVER skip checksum verification on important uploads -- ALWAYS send the OC-Checksum header with format ALGO:HASH (e.g., SHA256:abc123).

NEVER assume chunk assembly order -- chunks are assembled in numeric filename order regardless of upload sequence.

NEVER use relative paths in the Destination header -- ALWAYS use the full absolute URL including scheme and host.

ALWAYS authenticate WebDAV requests with basic auth (username + app password) or bearer token.

ALWAYS include the XML namespace declarations in PROPFIND request bodies -- omitting them causes property resolution failures.

ALWAYS use Depth: 1 as the default for directory listings -- it is the most common and safest option.

Essential Patterns

Pattern 1: List Directory Contents (PROPFIND)

curl 'https://cloud.example.com/remote.php/dav/files/username/Documents' \
  --user "$USER:$APP_PASSWORD" \
  --request PROPFIND \
  --header 'Depth: 1' \
  --data '<?xml version="1.0" encoding="UTF-8"?>
    <d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
      <d:prop>
        <d:getlastmodified/>
        <d:getcontentlength/>
        <d:getcontenttype/>
        <d:resourcetype/>
        <d:getetag/>
        <oc:fileid/>
        <oc:permissions/>
      </d:prop>
    </d:propfind>'

Response is a 207 Multi-Status XML with one <d:response> per item. The first response is the directory itself.

Pattern 2: Upload File with Metadata

curl 'https://cloud.example.com/remote.php/dav/files/username/report.pdf' \
  --user "$USER:$APP_PASSWORD" \
  --request PUT \
  --upload-file ./report.pdf \
  --header 'X-OC-MTime: 1700000000' \
  --header 'OC-Checksum: SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' \
  --header 'X-NC-WebDAV-AutoMkcol: 1'

The X-NC-WebDAV-AutoMkcol: 1 header auto-creates any missing parent directories.

Pattern 3: Move/Rename a File

curl 'https://cloud.example.com/remote.php/dav/files/username/old-name.txt' \
  --user "$USER:$APP_PASSWORD" \
  --request MOVE \
  --header 'Destination: https://cloud.example.com/remote.php/dav/files/username/subfolder/new-name.txt' \
  --header 'Overwrite: F'

Overwrite: F prevents overwriting an existing file at the destination. Use Overwrite: T (default) to allow it.

Pattern 4: Chunked Upload v2 (Large Files)

Three-step protocol for reliable large file uploads:

Step 1: Create upload directory

curl -X MKCOL --user "$USER:$APP_PASSWORD" \
  'https://cloud.example.com/remote.php/dav/uploads/username/myapp-unique-upload-id' \
  --header 'Destination: https://cloud.example.com/remote.php/dav/files/username/dest/largefile.zip'

Step 2: Upload chunks (5MB-5GB each)

# Chunk 1
curl -X PUT --user "$USER:$APP_PASSWORD" \
  'https://cloud.example.com/remote.php/dav/uploads/username/myapp-unique-upload-id/00001' \
  --data-binary @chunk1.bin \
  --header 'Destination: https://cloud.example.com/remote.php/dav/files/username/dest/largefile.zip' \
  --header 'OC-Total-Length: 52428800'

# Chunk 2
curl -X PUT --user "$USER:$APP_PASSWORD" \
  'https://cloud.example.com/remote.php/dav/uploads/username/myapp-unique-upload-id/00002' \
  --data-binary @chunk2.bin \
  --header 'Destination: https://cloud.example.com/remote.php/dav/files/username/dest/largefile.zip' \
  --header 'OC-Total-Length: 52428800'

Step 3: Assemble file (MOVE .file)

curl -X MOVE --user "$USER:$APP_PASSWORD" \
  'https://cloud.example.com/remote.php/dav/uploads/username/myapp-unique-upload-id/.file' \
  --header 'Destination: https://cloud.example.com/remote.php/dav/files/username/dest/largefile.zip' \
  --header 'OC-Total-Length: 52428800' \
  --header 'X-OC-MTime: 1700000000'

Constraints: Chunk names must be numbers 1-10000. Final chunk can be smaller than 5MB. Upload directory expires after 24 hours of inactivity. OC-Total-Length triggers quota validation (returns 507 Insufficient Storage if exceeded). To abort: DELETE the upload directory.

Pattern 5: Public Share Access (NC 29+)

# Public share without password
curl 'https://cloud.example.com/public.php/dav/files/SHARE_TOKEN/' \
  --request PROPFIND \
  --header 'Depth: 1' \
  --data '<?xml version="1.0"?><d:propfind xmlns:d="DAV:"><d:prop><d:resourcetype/></d:prop></d:propfind>'

# Public share with password
curl 'https://cloud.example.com/public.php/dav/files/SHARE_TOKEN/' \
  --user 'anonymous:' \
  --request PROPFIND \
  --header 'Depth: 1' \
  --data '<?xml version="1.0"?><d:propfind xmlns:d="DAV:"><d:prop><d:resourcetype/></d:prop></d:propfind>'

Password-protected shares use basic auth with username anonymous and the share password as the password.

Pattern 6: Download Folder as ZIP

curl 'https://cloud.example.com/remote.php/dav/files/username/ProjectFolder' \
  --user "$USER:$APP_PASSWORD" \
  --header 'Accept: application/zip' \
  --output project.zip

Optionally filter which files to include using the X-NC-Files header or files query parameter (JSON array of filenames).

Chunked Upload Decision Tree

File size > 5MB?
├── YES → Use chunked upload v2
│   ├── Generate unique upload ID (UUID recommended)
│   ├── MKCOL → create upload directory
│   ├── Split file into 5MB-5GB chunks
│   ├── PUT each chunk (numbered 00001-10000)
│   ├── MOVE .file → assemble at destination
│   └── On failure → DELETE upload directory to clean up
└── NO → Use simple PUT
    ├── Include OC-Checksum for integrity
    └── Include X-OC-MTime to preserve timestamp

Permission Flags (oc:permissions)

Reference Links

• references/methods.md -- DAV operations, property details, namespace reference, chunked upload protocol
• references/examples.md -- Complete curl examples for all DAV operations
• references/anti-patterns.md -- Common WebDAV mistakes and how to avoid them

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/index.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/basic.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/chunked_file_upload_v2.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/trashbin.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/versions.html