API Documentation

Complete guide to using the EmpireSphere API

Quick Start

Authentication

All API requests require an API key passed in the header:

curl -H "x-api-key: YOUR_API_KEY" https://api.empiresphere.com/api/files

Base URL

https://api.empiresphere.com/api

File Upload

POST

Upload one or multiple files to your storage.

Endpoint

/api/upload

Request

curl -X POST \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-folder: my-folder" \
    -F "files=@file1.pdf" \
    -F "files=@file2.jpg" \
    https://api.empiresphere.com/api/upload

Response

{
    "message": "Files uploaded and processed successfully",
    "files": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "file1.pdf",
            "path": "user123/my-folder/file1.pdf",
            "type": "application/pdf",
            "createdAt": "2024-03-21T12:00:00Z"
        }
    ]
}

List Files

GET

Retrieve a list of your files with pagination and filtering options.

Endpoint

/api/files

Parameters

  • page - Page number (default: 1)
  • limit - Items per page (default: 20)
  • folder - Filter by folder name
  • search - Search in file names
  • type - Filter by file type

Response

{
    "files": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "document.pdf",
            "path": "user123/default/document.pdf",
            "type": "application/pdf",
            "createdAt": "2024-03-21T12:00:00Z"
        }
    ],
    "pagination": {
        "total": 50,
        "pages": 3,
        "currentPage": 1,
        "perPage": 20
    }
}

Delete File

DELETE

Delete a specific file by its ID.

Endpoint

/api/files/:fileId

Request

curl -X DELETE \
    -H "x-api-key: YOUR_API_KEY" \
    https://api.empiresphere.com/api/files/123e4567-e89b-12d3-a456-426614174000

Response

{
    "message": "File deleted successfully"
}

Share File

POST

Generate a sharing link for a file.

Endpoint

/api/files/:fileId/share

Request

curl -X POST \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"expiresIn": 24}' \
    https://api.empiresphere.com/api/files/123e4567-e89b-12d3-a456-426614174000/share

Response

{
    "shareUrl": "https://api.empiresphere.com/api/share/abcdef123456",
    "expiresAt": "2024-03-22T12:00:00Z"
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

Success Codes

  • 200 - Success
  • 201 - Created

Error Codes

  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Server Error

Rate Limiting

The API implements rate limiting to ensure fair usage:

  • 100 requests per IP address per 15 minutes
  • Rate limit headers are included in all responses
  • When exceeded, requests will receive a 429 status code

SDK Libraries

JavaScript/TypeScript

npm install empiresphere-sdk
import { EmpireSphere } from 'empiresphere-sdk';

const client = new EmpireSphere('YOUR_API_KEY');
const files = await client.listFiles();

Python

pip install empiresphere
from empiresphere import EmpireSphere

client = EmpireSphere('YOUR_API_KEY')
files = client.list_files()

Security

API Keys

API keys should be kept secure and never exposed in client-side code. Each key has specific permissions and can be revoked at any time from the dashboard.

TLS Encryption

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

File Scanning

All uploaded files are automatically scanned for viruses and malware. Infected files will be rejected.

Webhooks

Get notified about events in your account by configuring webhooks.

Available Events

  • file.uploaded - When a new file is uploaded
  • file.deleted - When a file is deleted
  • file.shared - When a file is shared
  • share.accessed - When a shared file is accessed

Example Webhook Payload

{
    "event": "file.uploaded",
    "data": {
        "fileId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "document.pdf",
        "size": 1048576,
        "type": "application/pdf",
        "timestamp": "2024-03-21T12:00:00Z"
    }
}

Best Practices

Error Handling

Always implement proper error handling in your applications. The API returns detailed error messages to help you debug issues.

Rate Limiting

Implement exponential backoff when dealing with rate limits. Monitor the rate limit headers to stay within limits.

Optimization

  • Use appropriate page sizes when listing files
  • Implement caching where appropriate
  • Use compression for large file uploads
  • Clean up unused share links