API Endpoints
Complete reference for all MigrateClouds API endpoints.
Base URL
All API endpoints are relative to: https://api.migrateclouds.com/v1
API Conventions
Request Format
All requests should include the following headers:
| Header | Description |
|---|---|
| Authorization | Bearer token for authentication |
| Content-Type | application/json for request bodies |
| Accept | application/json for responses |
Response Format
All responses follow a standard format:
{
"success": true,
"data": { ... }, // Present on successful requests
"error": { ... } // Present on failed requests
}Error Handling
Error responses include detailed information about what went wrong:
{
"success": false,
"error": {
"code": "invalid_request",
"message": "The request was invalid",
"details": { ... } // Additional context about the error
}
}Pagination
Endpoints that return collections support pagination using the following parameters:
| Parameter | Description | Default |
|---|---|---|
| page | Page number (1-based) | 1 |
| limit | Items per page (max 100) | 20 |
| sort | Field to sort by (prefix with - for descending) | -createdAt |
Paginated responses include metadata about the current page and total results:
{
"success": true,
"data": [ ... ],
"pagination": {
"page": 1,
"limit": 20,
"totalItems": 45,
"totalPages": 3
}
}Files API
Endpoints for managing files across connected cloud storage services.
List Files
/filesRetrieves a list of files from a specified path in a connected storage service.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | Storage service (google-drive, onedrive, dropbox) |
| path | string | No | Path to list files from (defaults to root) |
| recursive | boolean | No | Whether to list files recursively (default: false) |
Example Request
GET /files?service=google-drive&path=/Documents Authorization: Bearer YOUR_API_KEY
Example Response
{
"success": true,
"data": [
{
"id": "1Abc123XyZ",
"name": "Report.pdf",
"type": "file",
"mimeType": "application/pdf",
"size": 2048576,
"path": "/Documents/Report.pdf",
"createdAt": "2023-01-15T12:30:45Z",
"modifiedAt": "2023-01-16T09:15:22Z"
},
{
"id": "2Def456UvW",
"name": "Images",
"type": "folder",
"path": "/Documents/Images",
"createdAt": "2022-12-10T08:20:15Z",
"modifiedAt": "2023-01-14T16:45:30Z"
}
]
}Get File Details
/files/:fileIdRetrieves detailed information about a specific file.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| fileId | string | Unique identifier of the file |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | Storage service (google-drive, onedrive, dropbox) |
Example Response
{
"success": true,
"data": {
"id": "1Abc123XyZ",
"name": "Report.pdf",
"type": "file",
"mimeType": "application/pdf",
"size": 2048576,
"path": "/Documents/Report.pdf",
"createdAt": "2023-01-15T12:30:45Z",
"modifiedAt": "2023-01-16T09:15:22Z",
"webViewLink": "https://drive.google.com/file/d/1Abc123XyZ/view",
"thumbnailUrl": "https://drive.google.com/thumbnail?id=1Abc123XyZ",
"owner": "[email protected]",
"shared": true
}
}Get Download URL
/files/:fileId/downloadGenerates a temporary download URL for a file.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | Storage service (google-drive, onedrive, dropbox) |
Example Response
{
"success": true,
"data": {
"downloadUrl": "https://download.migrateclouds.com/temp/abc123xyz",
"expiresAt": "2023-01-16T10:15:22Z"
}
}Delete File
/files/:fileIdPermanently deletes a file from the storage service.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | Storage service (google-drive, onedrive, dropbox) |
Example Response
{
"success": true,
"data": {
"message": "File deleted successfully"
}
}Warning
Rate Limits
To ensure fair usage and system stability, the MigrateClouds API implements rate limiting:
| Plan | Rate Limit | Burst Limit |
|---|---|---|
| Free | 60 requests per minute | 100 requests |
| Pro | 300 requests per minute | 500 requests |
| Enterprise | 1000 requests per minute | 2000 requests |
When you exceed your rate limit, the API will return a 429 Too Many Requests response. The response will include the following headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests you're permitted to make per minute |
| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds |
Webhooks
MigrateClouds provides webhooks to notify your application when events occur in your account.
Available Events
| Event | Description |
|---|---|
| transfer.completed | Triggered when a file transfer is completed successfully |
| transfer.failed | Triggered when a file transfer fails |
| file.created | Triggered when a new file is created |
| file.deleted | Triggered when a file is deleted |
Webhook Payload
Webhook payloads are sent as JSON in the request body. Each payload includes:
{
"id": "evt_123abc456def",
"type": "transfer.completed",
"created": "2023-01-16T15:45:30Z",
"data": {
// Event-specific data
}
}Webhook Security
X-MigrateClouds-Signature header. See the Webhooks documentation for details on how to verify this signature.