REST API

CocoCloud File Upload API

Automate uploads, metadata updates, and sharing. Bring your developer token and follow the sections below.

OpenAPI spec Quickstart (MD) Developer tokens

Authentication

Use a Sanctum personal access token. Add it to the Authorization header on every request.

Authorization: Bearer YOUR_TOKEN

Upload files

Multipart uploads handle chunking automatically. `upload_auto_delete` must match a key from `/api/v1/status -> uploads.auto_delete_periods` (use 0 for “do not auto-delete”).

Request sample

curl -X POST https://cococloud-drive.com/api/v1/uploads \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/report.pdf" \
  -F "upload_auto_delete=0" \
  -F "password=optional"

Successful response

{
  "status": "success",
  "data": {
    "download_id": "download_8BKkrWeGmMy1z8A",
    "download_link": "https://cococloud-drive.com/download/8BKkrWeGmMy1z8A",
    "preview_link": "https://cococloud-drive.com/8BKkrWeGmMy1z8A/file",
    "file": {
      "shared_id": "8BKkrWeGmMy1z8A",
      "name": "report.pdf",
      "size": "2 MB"
    }
  },
  "meta": {
    "message": "Uploaded successfully"
  }
}

Validation error example

{
  "status": "error",
  "message": "You cannot upload files of this type.",
  "code": "upload_error"
}

File Upload & Sharing Quickstart

This short guide focuses on the API endpoints required to upload files, manage metadata, and generate download links. Import resources/docs/api/openapi.yaml for the complete specification.

Prerequisites

Create a developer token from the dashboard (Developer API panel) or via POST /api/v1/developer/tokens.
Grant at least these scopes: files.read, files.write, files.share, uploads.write.
Add the token to every request:
```
Authorization: Bearer <token>
```

1. List files

curl -H "Authorization: Bearer <token>" \
  "https://cococloud-drive.com/api/v1/files?search=project"

Use the returned shared_id for the subsequent endpoints.

2. Upload a file

curl -X POST https://cococloud-drive.com/api/v1/uploads \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/report.pdf" \
  -F "upload_auto_delete=0" \
  -F "password=optional"

upload_auto_delete: use one of the keys from /api/v1/status -> uploads.auto_delete_periods.
password: applied only if your plan supports password-protected files.

Response excerpt:

{
  "status": "success",
  "data": {
    "download_link": "https://cococloud-drive.com/download/ABC123",
    "preview_link": "https://cococloud-drive.com/preview/ABC123",
    "file": {
      "shared_id": "ABC123",
      "name": "report.pdf",
      "size": "2 MB"
    }
  }
}

3. Update metadata

curl -X PATCH https://cococloud-drive.com/api/v1/files/{shared_id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Quarterly-Report.pdf","access_status":true}'

Set access_status to false to keep the file private, and include password to set or clear protection.

4. Generate a download link

curl -X POST https://cococloud-drive.com/api/v1/files/{shared_id}/download-link \
  -H "Authorization: Bearer <token>"

Use the returned download_link in your applications or emails. Links expire according to the configured download validity window.

5. Delete files

Single delete:

curl -X DELETE https://cococloud-drive.com/api/v1/files/{shared_id} \
  -H "Authorization: Bearer <token>"

Bulk delete:

curl -X POST https://cococloud-drive.com/api/v1/files/bulk/delete \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"shared_ids":["ABC123","XYZ789"]}'

Need another endpoint? Import the OpenAPI file or visit /api/docs for the full reference. Upload and file tests reside in tests/Feature/Api/V1.

Manage metadata

Rename files or toggle access/password protection.

Request sample

curl -X PATCH https://cococloud-drive.com/api/v1/files/{shared_id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Quarterly-Report.pdf","access_status":true}'

Successful response

{
  "status": "success",
  "data": {
    "file": {
      "shared_id": "8BKkrWeGmMy1z8A",
      "name": "Quarterly-Report.pdf",
      "access_status": true,
      "password_protected": false
    }
  },
  "meta": {
    "message": "Updated successfully"
  }
}

Generate download links

The response contains a short-lived link that redirects to the file download flow.

Request sample

curl -X POST https://cococloud-drive.com/api/v1/files/{shared_id}/download-link \
  -H "Authorization: Bearer <token>"

Successful response

{
  "status": "success",
  "data": {
    "download_link": "https://cococloud-drive.com/download/8BKkrWeGmMy1z8A/EQN9mEVR36dW1/robots.txt"
  }
}

Token scopes

files.read – List and inspect files you own.
files.write – Rename or delete files.
files.share – Generate expiring download links.
uploads.write – Upload new files via the API.

Endpoint reference

Each endpoint below lists the scopes it requires. Status is public.

Method	Path	Description	Scopes
GET	`/api/v1/status`	Retrieve upload options (auto delete periods, disallowed extensions).	Public
GET	`/api/v1/files`	List files (supports search & pagination).	files.read
GET	`/api/v1/files/{shared_id}`	Fetch file metadata by shared identifier.	files.read
PATCH	`/api/v1/files/{shared_id}`	Update file name, access status, or password.	files.write
DELETE	`/api/v1/files/{shared_id}`	Delete a single file and its storage object.	files.write
POST	`/api/v1/files/bulk/delete`	Delete multiple files in a single request.	files.write
POST	`/api/v1/files/{shared_id}/download-link`	Generate a fresh, expiring download link.	files.share
POST	`/api/v1/uploads`	Upload a file via multipart/chunked request.	uploads.write