> ## Documentation Index
> Fetch the complete documentation index at: https://help.hubsy.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Integrate Hubsy Cloud into your applications with our REST API

## Welcome to Hubsy Cloud API

The Hubsy Cloud API allows you to programmatically upload, download, manage, and share files from your applications. Build custom integrations, automate workflows, and create powerful file management solutions.

## Getting Started

<Steps>
  <Step title="Get API Key">
    1. Log in to your Hubsy Cloud account
    2. Go to Settings → API Keys
    3. Click "Generate New API Key"
    4. Copy and securely store your key

    <Warning>
      Never expose API keys in client-side code or public repositories.
    </Warning>
  </Step>

  <Step title="Make Your First Request">
    Test your API key with a simple request:

    ```bash theme={null}
    curl https://api.hubsy.cloud/v1/user/info \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Explore Endpoints">
    Check out our endpoint documentation below to see what's possible.
  </Step>
</Steps>

## Base URL

All API requests should be made to:

```
https://api.hubsy.cloud/v1
```

## Authentication

Hubsy Cloud API uses **Bearer token authentication**. Include your API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example Request

```bash theme={null}
curl https://api.hubsy.cloud/v1/files \
  -H "Authorization: Bearer sk_live_abc123xyz"
```

### API Key Scopes

Control what your API keys can access:

* **Read**: View files and folders
* **Write**: Upload and modify files
* **Delete**: Remove files and folders
* **Share**: Create and manage share links

<Tip>
  Create separate API keys for different applications with minimum required permissions.
</Tip>

## Rate Limits

To ensure service quality, API requests are rate limited:

| Plan       | Requests per minute |
| ---------- | ------------------- |
| Free       | 60                  |
| Pro        | 300                 |
| Enterprise | 1,000               |

### Rate Limit Headers

Response headers indicate your current status:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 250
X-RateLimit-Reset: 1640995200
```

<Note>
  When rate limit is exceeded, you'll receive a `429 Too Many Requests` response.
</Note>

## Response Format

All responses are in JSON format:

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    // Response data
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The file ID provided is invalid",
    "details": {}
  }
}
```

## Common Error Codes

| Code                    | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `invalid_request`       | Request is malformed or missing required parameters |
| `authentication_failed` | Invalid or missing API key                          |
| `permission_denied`     | Insufficient permissions for this operation         |
| `not_found`             | Resource not found                                  |
| `rate_limit_exceeded`   | Too many requests                                   |
| `storage_exceeded`      | Storage quota exceeded                              |
| `file_too_large`        | File exceeds size limit                             |

## Pagination

List endpoints support pagination:

### Request Parameters

* `page`: Page number (default: 1)
* `per_page`: Items per page (default: 50, max: 100)

### Example Request

```bash theme={null}
curl "https://api.hubsy.cloud/v1/files?page=2&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total_items": 150,
    "total_pages": 6
  }
}
```

## Webhooks

Receive real-time notifications for events:

### Available Events

* `file.uploaded` - New file uploaded
* `file.deleted` - File deleted
* `file.shared` - File shared
* `share.accessed` - Shared file accessed
* `storage.warning` - Approaching storage limit

### Setup

1. Go to Settings → Webhooks
2. Add webhook URL
3. Select events to monitor
4. Save configuration

<Card title="Webhook Documentation" icon="webhook" href="/api-reference/endpoint/webhook">
  Learn more about webhooks
</Card>

## SDKs & Libraries

Official SDKs for popular languages:

<CardGroup cols={2}>
  <Card title="JavaScript/Node.js" icon="js">
    ```bash theme={null}
    npm install @hubsy/sdk
    ```
  </Card>

  <Card title="Python" icon="python">
    ```bash theme={null}
    pip install hubsy-cloud
    ```
  </Card>

  <Card title="PHP" icon="php">
    ```bash theme={null}
    composer require hubsy/sdk
    ```
  </Card>

  <Card title="Ruby" icon="gem">
    ```bash theme={null}
    gem install hubsy-cloud
    ```
  </Card>
</CardGroup>

<Note>
  SDKs handle authentication, retries, and error handling automatically.
</Note>

## Quick Examples

### Upload a File

```javascript theme={null}
const response = await fetch('https://api.hubsy.cloud/v1/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});
```

### List Files

```python theme={null}
import requests

response = requests.get(
    'https://api.hubsy.cloud/v1/files',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
files = response.json()['data']
```

### Create Share Link

```bash theme={null}
curl -X POST https://api.hubsy.cloud/v1/shares \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_123", "password": "secret123", "expires_in": 86400}'
```

## Support

Need help with the API?

<CardGroup cols={2}>
  <Card title="API Status" icon="signal" href="https://status.hubsy.cloud">
    Check API uptime and incidents
  </Card>

  <Card title="Support" icon="envelope" href="mailto:api@hubsy.cloud">
    Contact API support team
  </Card>

  <Card title="Community" icon="comments" href="https://hubsy.cloud/community">
    Join our developer community
  </Card>

  <Card title="Changelog" icon="list" href="https://hubsy.cloud/changelog">
    View API updates and changes
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="File Operations" icon="file" href="/api-reference/endpoint/get">
    List, upload, and manage files
  </Card>

  <Card title="Sharing" icon="share" href="/api-reference/endpoint/create">
    Create and manage share links
  </Card>
</CardGroup>