Nextcloud Syntax Ocs API

nextcloud-syntax-ocs-api

Quick Reference

Endpoint Versioning

App-specific OCS endpoints: /ocs/v2.php/apps/{APPNAME}/api/v1/{endpoint}

Required Header

ALWAYS send this header with every OCS request:

OCS-APIRequest: true

Without this header, the server rejects the request. This header also serves as CSRF protection for API clients.

Authentication Methods

Response Format (JSON)

Request JSON with ?format=json or Accept: application/json header.

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": { }
  }
}

ALWAYS check ocs.meta.statuscode for the authoritative status — especially in v1 where HTTP status is always 200.

Key Endpoints

Share Types

Permissions Bitmask

Combine with bitwise OR: Read + Create = 1 | 4 = 5.

User Status Types

Critical Warnings

NEVER omit the OCS-APIRequest: true header — requests will be rejected with a login page redirect.

NEVER assume HTTP status codes reflect success in v1 — v1 ALWAYS returns HTTP 200. Check ocs.meta.statuscode instead.

NEVER parse XML when JSON is available — use ?format=json for simpler and less error-prone parsing.

NEVER hardcode server capabilities — ALWAYS check /cloud/capabilities for feature detection before using optional APIs.

NEVER create shares without validating shareType and permissions — invalid combinations produce cryptic errors.

ALWAYS use v2 endpoints for new code — they map OCS status codes to HTTP status codes for standard HTTP error handling.

ALWAYS use app passwords instead of real user passwords for API clients — obtain them via Login Flow v2.

ALWAYS include path and shareType when creating shares — they are required parameters.

Essential Patterns

Pattern 1: Basic OCS Request (JSON)

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

Pattern 2: Create a Public Link Share

curl -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -X POST \
  -d "path=/Documents/report.pdf&shareType=3&permissions=1" \
  "https://cloud.example.com/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json"

Pattern 3: OCSController for App Endpoints

namespace OCA\MyApp\Controller;

use OCP\AppFramework\Http\Attribute\NoAdminRequired;
use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\OCSController;
use OCP\IRequest;

class ApiController extends OCSController {
    public function __construct(
        string $appName,
        IRequest $request,
        private MyService $service,
    ) {
        parent::__construct($appName, $request);
    }

    #[NoAdminRequired]
    public function getData(int $id): DataResponse {
        $item = $this->service->find($id);
        return new DataResponse(['item' => $item]);
    }
}

Register the OCS route in appinfo/routes.php:

return [
    'ocs' => [
        ['name' => 'api#getData', 'url' => '/api/v1/data/{id}', 'verb' => 'GET'],
    ],
];

Accessible at: /ocs/v2.php/apps/myapp/api/v1/data/42

Pattern 4: Capabilities Check Before Feature Use

# Check if the server supports file sharing
CAPS=$(curl -s -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  "https://cloud.example.com/ocs/v1.php/cloud/capabilities?format=json")

# Parse capabilities (using jq)
echo "$CAPS" | jq '.ocs.data.capabilities.files_sharing'

ALWAYS check capabilities before calling optional APIs — apps may be disabled or features restricted by admin.

Pattern 5: Set User Status with Custom Message

curl -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"statusType": "away"}' \
  "https://cloud.example.com/ocs/v2.php/apps/user_status/api/v1/user_status/status"

curl -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"statusIcon": "☕", "message": "On a break", "clearAt": null}' \
  "https://cloud.example.com/ocs/v2.php/apps/user_status/api/v1/user_status/message/custom"

Pattern 6: Share with Advanced Attributes

# Create a file request (upload-only public share)
curl -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  -X POST \
  -d "path=/Uploads&shareType=3&permissions=4" \
  --data-urlencode 'attributes=[{"scope":"fileRequest","key":"enabled","value":true}]' \
  "https://cloud.example.com/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json"

# Create a share with download disabled
curl -u "$USER:$APP_PASSWORD" \
  -H "OCS-APIRequest: true" \
  -X POST \
  -d "path=/Documents/secret.pdf&shareType=3&permissions=1" \
  --data-urlencode 'attributes=[{"scope":"permissions","key":"download","value":false}]' \
  "https://cloud.example.com/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json"

v1 vs v2 Status Code Mapping

ALWAYS prefer v2 for new integrations — standard HTTP error handling works out of the box.

Create Share Parameters

Reference Links

• references/methods.md -- All OCS endpoints, response format details, share API reference
• references/examples.md -- curl examples for all major endpoints
• references/anti-patterns.md -- Common OCS API mistakes and corrections

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/index.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-share-api.html
• https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-status-api.html
• https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/rest_apis.html