Cloudy API Reference

The Cloudy REST API is organized around REST, uses standard HTTP verbs and status codes, and returns JSON. You can use the API to manage files, folders, teams, and automate your cloud storage workflows.

Base URL

                        // Production

                        https://api.cloudy.io/v2

                        // Sandbox (test environment)

                        https://api-sandbox.cloudy.io/v2

99.97%

Uptime SLA

< 120ms

Avg Response Time

v2.4.1

Current Version

Quick Start

Get your API key from the Developer Dashboard, then make your first request:

                    curl https://api.cloudy.io/v2/users/me \

                      -H "Authorization: Bearer cs_live_sk_4f8a2b1c9d3e7f6a5b8c" \

                      -H "Content-Type: application/json"

Authentication

The Cloudy API uses Bearer token authentication. Include your API key in the Authorization header of every request. API keys are scoped and can be restricted to specific resources and permissions.

Security Notice: Never expose your API keys in client-side code or public repositories. Use environment variables or a secrets manager. Keys prefixed with cs_live_sk_ have production access.

Header Format

                    Authorization: Bearer <your_api_key>

                    X-Cloudy-Version: 2024-08-15 // optional, API version pinning

Key Types

Prefix	Environment	Access Level
cs_live_sk_	Production	Full access based on scope
cs_test_sk_	Sandbox	Sandbox resources only
cs_live_pk_	Production	Public / read-only

OAuth 2.0

For user-delegated access, Cloudy supports OAuth 2.0 with the Authorization Code flow. This is required for actions performed on behalf of end users.

                    // Step 1: Redirect user to authorization URL

                    https://cloudy.io/oauth/authorize?

                      client_id=your_client_id

                      &redirect_uri=https://yourapp.com/callback

                      &response_type=code

                      &scope=files.read files.write teams.read

                      &state=random_csrf_token

Rate Limiting

API requests are limited based on your plan. Rate limit information is included in response headers. When you exceed the limit, the API returns a 429 Too Many Requests status.

Plan	Requests / min	Burst Limit	Concurrent
Free	60	10	5
Pro	600	50	20
Business	3,000	200	50
Enterprise	Custom	Custom	Custom

Rate Limit Headers

                    X-RateLimit-Limit: 600

                    X-RateLimit-Remaining: 598

                    X-RateLimit-Reset: 1718841600 // Unix timestamp

                    Retry-After: 42 // only on 429 responses

Error Handling

Cloudy uses conventional HTTP response codes. Successful requests return 2xx codes, client errors return 4xx codes, and server errors return 5xx codes.

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource successfully created
204	No Content	Request succeeded with no response body
400	Bad Request	Malformed request or invalid parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions for this action
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded — retry after delay
500	Internal Server Error	Something went wrong on our end

Error Response Format

                    {

                      "error": {

                        "code": "resource_not_found",

                        "message": "The file with ID 'fl_9x2k4m' was not found.",

                        "status": 404,

                        "request_id": "req_8f7a6b5c4d3e2f1a",

                        "doc_url": "https://docs.cloudy.io/errors/resource_not_found"

                      }

                    }

Pagination

All top-level API resources support cursor-based pagination. Use the limit and cursor query parameters to navigate through large collections.

                    // Request

                    GET /v2/files?limit=25&cursor=eyJpZCI6ImZsXzEyMyJ9

                    // Response

                    {

                      "data": [ /* ... */ ],

                      "has_more": true,

                      "next_cursor": "eyJpZCI6ImZsXzQ1NiJ9",

                      "total_count": 1284

                    }

Users

The User object represents an individual account in your Cloudy organization. You can create, update, and manage user accounts programmatically.

GET /users/me

Retrieve the currently authenticated user's profile information.

Response 200

                        {

                          "id": "usr_3k8f2m9p1q",

                          "email": "sarah.chen@acmecorp.io",

                          "display_name": "Sarah Chen",

                          "avatar_url": "https://cdn.cloudy.io/avatars/usr_3k8f2m9p1q.jpg",

                          "role": "admin",

                          "storage_used": 47283916800,

                          "storage_quota": 107374182400,

                          "two_factor_enabled": true,

                          "created_at": "2023-04-12T08:31:44Z",

                          "last_login": "2024-06-18T14:22:01Z"

                        }

GET /users

List all users in your organization. Requires teams.read scope.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results (1–100, default: 20)
cursor	string	Pagination cursor from previous response
role	string	Filter by role: admin, member, viewer

PATCH /users/:user_id

Update a user's profile information. Only provided fields will be modified.

Request Body

                        {

                          "display_name": "Sarah Chen-Williams",

                          "role": "admin"

                        }

DELETE /users/:user_id

Permanently delete a user. Their files will be transferred to the organization admin or deleted based on the transfer_to parameter.

Destructive action: This operation cannot be undone. All user sessions will be revoked immediately. A 7-day grace period applies before permanent deletion.

Files

Files are the core resource in Cloudy. Each file has metadata including size, MIME type, checksum, and version history. The API supports both metadata operations and direct file upload/download via presigned URLs.

POST /files

Create a new file entry and generate a presigned upload URL. The upload must be completed within 15 minutes of generating the presigned URL.

Request Body

                        {

                          "name": "Q3_Financial_Report.pdf",

                          "mime_type": "application/pdf",

                          "size": 2458624,

                          "parent_folder_id": "fld_7h3k9m2p",

                          "checksum_sha256": "a1b2c3d4e5f6..."

                        }

Response 201

                        {

                          "id": "fl_8k2m4p9q1r",

                          "upload_url": "https://upload.cloudy.io/v2/presigned/fl_8k2m4p9q1r?sig=...",

                          "upload_expires_at": "2024-06-20T10:45:00Z",

                          "status": "pending_upload"

                        }

GET /files/:file_id

Retrieve metadata for a specific file. To download the file content, use the download_url field or call GET /files/:id/download.

Response 200

                        {

                          "id": "fl_8k2m4p9q1r",

                          "name": "Q3_Financial_Report.pdf",

                          "mime_type": "application/pdf",

                          "size": 2458624,

                          "checksum_sha256": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",

                          "parent_folder_id": "fld_7h3k9m2p",

                          "owner_id": "usr_3k8f2m9p1q",

                          "created_at": "2024-06-19T10:30:00Z",

                          "updated_at": "2024-06-19T10:32:14Z",

                          "version": 3,

                          "download_url": "https://dl.cloudy.io/v2/fl_8k2m4p9q1r?token=...",

                          "shared": false,

                          "tags": ["finance", "q3-2024", "confidential"]

                        }

GET /files

List files in your account. Supports filtering by folder, type, and date range.

Query Parameters

Parameter	Type	Description
folder_id	string	Filter by parent folder ID
mime_type	string	Filter by MIME type (e.g., image/png)
modified_after	string	ISO 8601 datetime filter
sort_by	string	name, size, modified_at (default)

PUT /files/:file_id

Replace an existing file with a new version. Increments the file version number automatically.

DELETE /files/:file_id

Move a file to trash. Files in trash are retained for 30 days before permanent deletion. Use DELETE /trash/:file_id for immediate permanent deletion.

Folders

Folders organize your files hierarchically. Nested folders are supported up to 50 levels deep. Each folder can have independent sharing and permission settings.

POST /folders

Create a new folder.

                        {

                          "name": "Marketing_Assets",

                          "parent_folder_id": "fld_root",

                          "color": "#4f46e5" // optional, for UI organization

                        }

Response 201

                        {

                          "id": "fld_9m3k2p8q",

                          "name": "Marketing_Assets",

                          "parent_folder_id": "fld_root",

                          "path": "/Marketing_Assets",

                          "created_at": "2024-06-20T09:15:33Z",

                          "item_count": 0

                        }

GET /folders/:folder_id/contents

List all files and sub-folders within a folder. Supports pagination.

PATCH /folders/:folder_id

Update folder metadata including name, color, and parent (move folder).

Shared Links

Shared links provide public or restricted access to files and folders. You can configure expiration dates, password protection, and download limits.

POST /files/:file_id/share

Generate a shareable link for a file.

                        {

                          "access_level": "view",

                          "password": "optional_password_123",

                          "expires_at": "2024-07-20T00:00:00Z",

                          "max_downloads": 10

                        }

Response 201

                        {

                          "id": "shr_4k8m2p9q",

                          "url": "https://share.cloudy.io/s/aB3xK9mP",

                          "access_level": "view",

                          "password_protected": true,

                          "expires_at": "2024-07-20T00:00:00Z",

                          "max_downloads": 10,

                          "download_count": 0,

                          "created_at": "2024-06-20T11:42:08Z"

                        }

DELETE /files/:file_id/share/:share_id

Revoke a shared link immediately. Anyone with the link will no longer have access.

Teams

Teams allow you to group users and manage shared resources. Each team can have its own storage quota, permissions, and collaboration settings.

GET /teams

List all teams the authenticated user belongs to.

POST /teams

Create a new team. Requires teams.write scope.

                        {

                          "name": "Engineering",

                          "description": "Engineering department shared workspace",

                          "storage_quota": 536870912000,

                          "member_ids": ["usr_3k8f2m9p1q", "usr_7j2k4m8n"]

                        }

POST /teams/:team_id/members

Add one or more members to a team. Members can be assigned roles: admin, editor, or viewer.

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in your Cloudy account. Configure webhook endpoints to subscribe to specific event types.

POST /webhooks

Register a new webhook endpoint.

                        {

                          "url": "https://yourapp.com/webhooks/cloudy",

                          "events": [

                            "file.created",

                            "file.deleted",

                            "file.shared",

                            "folder.created"

                          ],

                          "secret": "whsec_your_signing_secret"

                        }

Webhook Payload

                    {

                      "id": "evt_1k3m5p8q2r",

                      "type": "file.created",

                      "timestamp": "2024-06-20T14:32:11Z",

                      "data": {

                        "file_id": "fl_8k2m4p9q1r",

                        "name": "Q3_Financial_Report.pdf",

                        "size": 2458624,

                        "owner_id": "usr_3k8f2m9p1q"

                      },

                      "signature": "sha256=abc123def456..."

                    }

Supported Events

Event	Description
file.created	A new file was uploaded
file.updated	A file was modified or replaced
file.deleted	A file was moved to trash
file.shared	A shareable link was created
folder.created	A new folder was created
team.member_added	A user was added to a team
team.member_removed	A user was removed from a team

Search

Full-text search across file names, content (for supported formats), tags, and metadata. Results are ranked by relevance and can be filtered by type, date, and owner.

GET /search

Search across all accessible files and folders.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query string
type	string	No	file or folder
file_type	string	No	MIME type filter (e.g., application/pdf)
owner_id	string	No	Filter by file owner

Example

                        GET /v2/search?q=quarterly+report&type=file&file_type=application/pdf

                        {

                          "results": [

                            {

                              "type": "file",

                              "id": "fl_8k2m4p9q1r",

                              "name": "Q3_Financial_Report.pdf",

                              "score": 0.94,

                              "highlights": {

                                "name": ["<mark>Q3</mark>_Financial_<mark>Report</mark>.pdf"]

                              }

                            }

                          ],

                          "total": 12,

                          "took_ms": 34

                        }

Audit Logs

Audit logs provide a detailed record of all actions performed within your organization. Available on Business and Enterprise plans. Logs are retained for 365 days.

GET /audit-logs

Retrieve audit log entries. Requires audit.read scope.

Query Parameters

Parameter	Type	Description
start_date	string	ISO 8601 datetime (default: 7 days ago)
end_date	string	ISO 8601 datetime (default: now)
actor_id	string	Filter by user who performed the action
action	string	Filter by action type (e.g., file.download)
ip_address	string	Filter by source IP address

Response 200

                        {

                          "data": [

                            {

                              "id": "log_9k3m2p8q1r",

                              "timestamp": "2024-06-20T14:32:11Z",

                              "actor": {

                                "id": "usr_3k8f2m9p1q",

                                "email": "sarah.chen@acmecorp.io"

                              },

                              "action": "file.downloaded",

                              "resource": {

                                "type": "file",

                                "id": "fl_8k2m4p9q1r",

                                "name": "Q3_Financial_Report.pdf"

                              },

                              "ip_address": "203.0.113.42",

                              "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

                            }

                          ]

                        }

Metadata

Attach custom key-value metadata to files and folders. Metadata is indexed and searchable. Each resource can have up to 50 metadata templates with 200 fields each.

POST /files/:file_id/metadata

Set custom metadata on a file.

                        {

                          "template": "document_classification",

                          "fields": {

                            "department": "Finance",

                            "classification": "confidential",

                            "retention_period": "7_years",

                            "review_date": "2025-06-20"

                          }

                        }

GET /files/:file_id/metadata

Retrieve all metadata associated with a file.

Trash & Recovery

Deleted files and folders are moved to trash and retained for 30 days. During this period, they can be restored to their original location or permanently deleted.

GET /trash

List all items currently in trash.

POST /trash/:resource_id/restore

Restore a trashed item to its original location. If the original folder no longer exists, it will be restored to the root.

DELETE /trash/:resource_id

Permanently delete an item from trash. This action is irreversible.

File Versioning

Cloudy automatically maintains version history for all files. Previous versions can be accessed, downloaded, or restored. Version retention depends on your plan.

GET /files/:file_id/versions

List all versions of a file.

                        {

                          "data": [

                            {

                              "version_id": "ver_4k8m2p9q",

                              "version_number": 3,

                              "size": 2458624,

                              "uploaded_by": "usr_3k8f2m9p1q",

                              "created_at": "2024-06-19T10:32:14Z",

                              "checksum_sha256": "a1b2c3d4..."

                            },

                            {

                              "version_id": "ver_2j6k8m4n",

                              "version_number": 2,

                              "size": 2104832,

                              "uploaded_by": "usr_3k8f2m9p1q",

                              "created_at": "2024-06-18T15:21:44Z"

                            }

                          ]

                        }

POST /files/:file_id/versions/:version_id/restore

Restore a previous version. This creates a new version that is a copy of the specified version.