API Documentation

Postman Collection

Import our ready-to-use Postman collection to quickly test all API endpoints.

Download Collection

In Postman: File → Import → Link → Paste the URL above, or use the downloaded JSON file.

Getting Started

Files Hub provides a RESTful API for managing file storage. All API endpoints require authentication using an API key.

Base URL: https://fileshub.zaions.com/api/v1

Authentication

All API requests must include your API key in the X-API-Key header. 

curl -X GET "https://fileshub.zaions.com/api/v1/objects" \
  -H "X-API-Key: your-api-key-here"

API keys can be created and managed in the Nova admin panel under your project settings.

Endpoints

GET /api/v1/objects

List all files in your project

Query Parameters

Parameter Type Description
page integer Page number for pagination
per_page integer Items per page (default: 15, max: 100)

Response

{
  "data": [
    {
      "public_id": "abc123",
      "original_name": "document.pdf",
      "mime_type": "application/pdf",
      "size": 102400,
      "url": "https://example.com/storage/...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}
POST /api/v1/objects

Upload a new file

Request Body (multipart/form-data)

Field Type Required Description
file file Yes The file to upload (max 10MB)

Example

curl -X POST "https://fileshub.zaions.com/api/v1/objects" \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@/path/to/document.pdf"
GET /api/v1/objects/{public_id}

Get a specific file's metadata

Response

{
  "data": {
    "public_id": "abc123",
    "original_name": "document.pdf",
    "mime_type": "application/pdf",
    "size": 102400,
    "url": "https://example.com/storage/...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
DELETE /api/v1/objects/{public_id}

Delete a file

Example

curl -X DELETE "https://fileshub.zaions.com/api/v1/objects/abc123" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "message": "Object deleted successfully"
}

Email API

Files Hub also provides a powerful email sending API. Send transactional emails using pre-defined templates or custom content.

Permission Required: API key must have email permission to send emails.

POST /api/v1/emails/send

Send an email using a template or raw content

Request Body (Template-Based)

Field Type Required Description
to string Yes Recipient email address
to_name string No Recipient name
template string Yes* Template slug (required for template emails)
variables object No Template variables (key-value pairs)
cc array No CC email addresses (max 10)
bcc array No BCC email addresses (max 10)
reply_to string No Reply-to email address
attachments array No Array of StoredObject public_ids (max 5)
scheduled_at string No ISO 8601 datetime to schedule sending

Example (Template)

curl -X POST "https://fileshub.zaions.com/api/v1/emails/send" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "to_name": "John Doe",
    "template": "welcome",
    "variables": {
      "name": "John",
      "company": "Acme Inc"
    }
  }'

Request Body (Raw Content)

Field Type Required Description
to string Yes Recipient email address
subject string Yes Email subject line
body_html string Yes* HTML email body (required if no body_text)
body_text string Yes* Plain text email body (required if no body_html)

Example (Raw Content)

curl -X POST "https://fileshub.zaions.com/api/v1/emails/send" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Your Order Confirmation",
    "body_html": "<h1>Order Confirmed</h1><p>Thank you for your order!</p>",
    "body_text": "Order Confirmed\n\nThank you for your order!"
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "01HXYZ123ABC456DEF789",
    "status": "sent",
    "scheduled_at": null,
    "sent_at": "2024-01-15T10:30:00Z"
  }
}
GET /api/v1/emails/templates

List all available email templates

Example

curl -X GET "https://fileshub.zaions.com/api/v1/emails/templates" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "success": true,
  "data": [
    {
      "slug": "welcome",
      "name": "Welcome Email",
      "description": "Sent to new users after registration",
      "category": "onboarding",
      "subject": "Welcome to {{ app_name }}!",
      "variables": ["name", "company", "login_url"]
    }
  ]
}
GET /api/v1/emails

List email logs for your project

Query Parameters

Parameter Type Description
page integer Page number for pagination
per_page integer Items per page (default: 50, max: 100)
status string Filter by status: pending, sent, failed, scheduled

Response

{
  "success": true,
  "data": [
    {
      "id": "01HXYZ123ABC",
      "to_email": "user@example.com",
      "subject": "Welcome!",
      "template": "welcome",
      "status": "sent",
      "scheduled_at": null,
      "sent_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 50,
    "total": 142
  }
}
GET /api/v1/emails/{public_id}

Get details of a specific email

Response

{
  "success": true,
  "data": {
    "id": "01HXYZ123ABC",
    "to_email": "user@example.com",
    "to_name": "John Doe",
    "cc_emails": ["manager@example.com"],
    "bcc_emails": null,
    "from_email": "noreply@yourapp.com",
    "from_name": "Your App",
    "reply_to": "support@yourapp.com",
    "subject": "Welcome to Your App!",
    "template": "welcome",
    "status": "sent",
    "error_message": null,
    "scheduled_at": null,
    "sent_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

JavaScript SDK

We provide a TypeScript SDK for easy integration with JavaScript applications.

Installation

npm install files-hub-sdk
# or
yarn add files-hub-sdk

Usage

import { FilesHub } from 'files-hub-sdk';

const client = new FilesHub({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://fileshub.zaions.com/api/v1'
});

// Upload a file
const file = document.querySelector('input[type="file"]').files[0];
const result = await client.upload(file);
console.log(result.url);

// List files
const files = await client.list({ page: 1, perPage: 20 });

// Get file metadata
const file = await client.get('abc123');

// Delete a file
await client.delete('abc123');

Error Responses

The API uses standard HTTP status codes to indicate success or failure.

File Storage API

Status Code Description
200 Success
201 Created (file uploaded successfully)
400 Bad Request (invalid parameters)
401 Unauthorized (invalid or missing API key)
403 Forbidden (origin not whitelisted or missing permission)
404 Not Found (file does not exist)
413 Payload Too Large (file exceeds size limit)
500 Internal Server Error

Email API

Status Code Description
201 Email sent or scheduled successfully
401 Unauthorized (invalid API key)
403 Forbidden (API key missing email permission)
404 Email not found
422 Validation error (invalid email, missing fields, invalid template)
500 Internal Server Error (email sending failed)
503 Service Unavailable (email service temporarily down)

Error Response Format

File Storage API errors:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Email API errors:

{
  "success": false,
  "message": "The specified email template does not exist or is inactive."
}

Rate Limiting

API requests are rate limited to ensure fair usage. Current limits:

File Storage API

  • Uploads: 60 requests per minute
  • Other requests: 120 requests per minute

Email API

  • Send emails: Default 60 requests per minute (configurable per API key)
  • Daily limit: 450 emails per day per email account (configurable in Nova admin)
  • Other requests: 120 requests per minute

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Need Help?

If you have questions or need assistance with the API, please contact us.

Contact Support