API Reference

CloudSync provides a comprehensive REST API for programmatic access to all functionality. The API is designed to be simple, consistent, and follows REST principles.

## Authentication

All API requests require authentication using an API token. Tokens can be generated in the CloudSync web console or via the CLI.

API tokens should be included in the Authorization header: `Authorization: Bearer YOUR_API_TOKEN`

Tokens have configurable expiration (default: 90 days) and can be revoked at any time. Rotation is recommended every 6 months.

## Base URL

The API base URL depends on your region:

- North America: https://api.cloudsync.io
- Europe: https://api.eu.cloudsync.io
- Asia Pacific: https://api.ap.cloudsync.io

## Endpoints

### List Workspaces

Retrieve all workspaces accessible to the authenticated user.

**Request:**
```
GET /api/v1/workspaces
```

**Parameters:**
- `limit` (optional): Maximum number of results (default: 50, max: 100)
- `offset` (optional): Number of results to skip (default: 0)

**Response:**
```json
{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "Engineering Team",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "member_count": 12
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

### Get Workspace Details

Retrieve detailed information about a specific workspace.

**Request:**
```
GET /api/v1/workspaces/{workspace_id}
```

**Response:**
```json
{
  "id": "ws_abc123",
  "name": "Engineering Team",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "member_count": 12,
  "storage_used_gb": 245.6,
  "storage_limit_gb": 1024,
  "encryption": "aes256",
  "region": "us-east-1",
  "owner": {
    "id": "user_xyz789",
    "email": "owner@example.com"
  }
}
```

### List Sync Items

Retrieve all items being synchronized in a workspace.

**Request:**
```
GET /api/v1/workspaces/{workspace_id}/items
```

**Query Parameters:**
- `status`: Filter by status (syncing, synced, failed, paused)
- `type`: Filter by type (file, folder)

**Response:**
```json
{
  "items": [
    {
      "id": "item_123",
      "name": "project_data.zip",
      "type": "file",
      "status": "synced",
      "size_bytes": 1073741824,
      "modified_at": "2024-01-20T14:25:00Z",
      "sync_percentage": 100
    }
  ]
}
```

### Get Sync Status

Retrieve real-time synchronization status for an item.

**Request:**
```
GET /api/v1/workspaces/{workspace_id}/items/{item_id}/status
```

**Response:**
```json
{
  "item_id": "item_123",
  "status": "syncing",
  "progress": {
    "transferred_bytes": 536870912,
    "total_bytes": 1073741824,
    "percentage": 50,
    "estimated_remaining_seconds": 120
  },
  "last_updated": "2024-01-20T14:26:30Z"
}
```

### List Sync Members

Retrieve all team members with access to a workspace.

**Request:**
```
GET /api/v1/workspaces/{workspace_id}/members
```

**Response:**
```json
{
  "members": [
    {
      "id": "user_123",
      "email": "alice@example.com",
      "role": "admin",
      "joined_at": "2024-01-15T10:30:00Z",
      "last_active": "2024-01-20T16:45:00Z"
    },
    {
      "id": "user_456",
      "email": "bob@example.com",
      "role": "member",
      "joined_at": "2024-01-16T09:00:00Z",
      "last_active": "2024-01-20T15:20:00Z"
    }
  ]
}
```

### Pause Synchronization

Pause synchronization for a specific item. This stops active syncing but does not delete any data.

**Request:**
```
POST /api/v1/workspaces/{workspace_id}/items/{item_id}/pause
```

**Response:**
```json
{
  "item_id": "item_123",
  "status": "paused",
  "message": "Synchronization paused successfully"
}
```

### Resume Synchronization

Resume synchronization for a paused item.

**Request:**
```
POST /api/v1/workspaces/{workspace_id}/items/{item_id}/resume
```

**Response:**
```json
{
  "item_id": "item_123",
  "status": "syncing",
  "message": "Synchronization resumed"
}
```

## Error Handling

CloudSync API returns standard HTTP status codes:

- 200: Success
- 400: Bad request (invalid parameters)
- 401: Unauthorized (invalid or missing token)
- 403: Forbidden (insufficient permissions)
- 404: Not found
- 429: Rate limited (too many requests)
- 500: Server error

Error responses include a JSON body with details:

```json
{
  "error": {
    "code": "INVALID_WORKSPACE_ID",
    "message": "Workspace not found or access denied",
    "details": {
      "workspace_id": "ws_invalid"
    }
  }
}
```

## Rate Limiting

API requests are limited to:
- 100 requests per minute per API token (can be increased for enterprise)
- 1000 requests per hour per IP address
- Maximum request size: 10 MB

Rate limit status is included in response headers:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Unix timestamp when limit resets

## Webhook Integration

CloudSync supports webhooks for real-time event notifications. Webhook events include sync completion, member invitations, and security alerts.

Webhooks are delivered as HTTP POST requests with a JSON payload and can be configured to retry up to 5 times on failure.
