Which AI agents work with Files Hub?

Files Hub publishes machine-readable integration docs for Claude Code, ChatGPT, Cursor, and any LLM-based coding assistant. Point the agent at /ai-integration or /files-hub-ai-integration.json.

How does an AI agent authenticate to Files Hub?

The user provides a Files Hub API key in the agent's environment. The agent then sends X-API-Key: with every write request.

Where does an AI agent learn the Files Hub API surface?

Two canonical feeds: /files-hub-ai-integration.json (JSON) and /files-hub-ai-integration.md (Markdown). Both enumerate endpoints, params, and example calls.

AI Integration Guide

Download for AI Agents

Download the specification files to provide to your AI code agent for automatic implementation.

Download JSON Download Markdown

Quick Start

1. Environment Variables

# Required
FILES_HUB_API_KEY=fh_live_your_api_key_here
FILES_HUB_BASE_URL=https://fileshub.zaions.com

2. Base URL & Authentication

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

Auth Header: X-API-Key: your-api-key

Email Sending (Multi-Provider)

Send emails via API with support for 3 configurable providers. The admin configures accounts in the dashboard; your app just calls the API.

Provider	Type	Best For
Gmail SMTP	Direct SMTP	Small volume, personal projects (450/day free)
Brevo	API	Transactional emails, higher volume (300/day free)
Mailtrap	API	Testing and staging environments, deliverability testing

Provider selection and credentials are managed via admin panel. API callers use the same endpoint regardless of which provider is active. Round-robin rotation distributes load across multiple configured accounts.

Core Services (22 Categories)

Service	Permission	Key Endpoints
File Storage	`read`, `write`	POST/GET/DELETE /objects
Email	`email`	POST /emails/send (queued by default; optional `domain` + `queue:false`), GET /emails/templates, GET /jobs/{job_id}, /email-schedules CRUD + run (recurring cron sends), template CRUD via /emails/templates
URL Shortener	`url_shortener`	POST/GET/DELETE /short-urls, GET /s/{code}
QR Code	`qr_code`	POST /qr-codes, GET /qr-codes/{id}/download
Image Processing	`image_processing`	POST /images/{resize,compress,crop,convert,info}
PDF Generation	`pdf_generation`	POST /pdfs/from-html, POST /pdfs/from-markdown
Push Notifications	`push_notifications`	POST /push/{subscribe,send-to-token,send-to-topic}
Webhooks	`webhooks`	POST/GET/DELETE /webhooks
Feature Flags	`feature_flags`	POST/GET/DELETE /feature-flags
Link Preview	`link_preview`	GET /link-preview?url=
Analytics	`analytics`	POST /analytics/track, GET /analytics/summary
Audit Log	`audit_log`	GET /audit-logs
Paste Bin	`paste_bin`	POST/GET/DELETE /pastes
IP Geolocation	`ip_geolocation`	GET /geoip/lookup, GET /geoip/me
Scheduled Tasks	`scheduled_tasks`	POST/GET/DELETE /scheduled-tasks
Encryption Vault	`encryption_vault`	POST/GET/DELETE /vault, POST /vault/encrypt
Data Export	`data_export`	POST /export/{csv,excel,json}
Health Monitoring	`health_monitoring`	POST/GET/DELETE /uptime-monitors
Contact Form	`contact_form`	POST/GET /contact-form
OTP	`otp`	POST /otp/send, POST /otp/verify
Notification Center	`notification_center`	POST/GET/PATCH/DELETE /notifications
App Version	`app_version`	GET /app-versions/check, POST /app-versions

File Storage API

Upload and manage files with public/private visibility.

POST /api/v1/objects

Upload a file (multipart/form-data)

curl -X POST "https://fileshub.zaions.com/api/v1/objects" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@document.pdf" \
  -F "visibility=public"

Response

{"public_id": "01ABC...", "url": "https://fileshub.zaions.com/api/v1/objects/01ABC...", "mime_type": "application/pdf", "size_bytes": 102400}

Other: GET /objects (list), GET /objects/{id} (download), DELETE /objects/{id}

URL Shortener

Create short URLs with click tracking. Permission: url_shortener

POST /api/v1/short-urls

curl -X POST "https://fileshub.zaions.com/api/v1/short-urls" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"original_url": "https://example.com/long-url", "title": "My Link", "max_clicks": 1000}'

{"data": {"public_id": "...", "code": "x7k9m", "short_url": "https://fileshub.zaions.com/s/x7k9m", "click_count": 0}}

Redirect: GET /s/{code} (no auth) | Other: GET/DELETE /short-urls/{id}

QR Code Generator

Generate QR codes in PNG/SVG. Permission: qr_code

POST /api/v1/qr-codes

{"data": "https://example.com", "type": "url", "format": "png", "size": 300, "error_correction": "M"}

Types: url, text, wifi, vcard, email, phone | Formats: png, svg | Size: 100-1000

Image Processing

Resize, compress, crop, convert images. Permission: image_processing

POST /api/v1/images/resize

curl -X POST "https://fileshub.zaions.com/api/v1/images/resize" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@image.jpg" -F "width=800" -F "height=600"

Or use source_public_id to process existing stored file

Other: /images/compress, /images/crop, /images/convert, /images/info

PDF Generation

Generate PDFs from HTML/Markdown. Permission: pdf_generation

POST /api/v1/pdfs/from-html

{"html": "Report
Content
", "title": "My Report", "page_size": "a4", "orientation": "portrait"}

Other: POST /pdfs/from-markdown, GET /pdfs/{id}/download

Push Notifications (FCM)

Send push notifications via Firebase. Permission: push_notifications

POST /api/v1/push/send-to-token

{"device_token": "fcm-token", "title": "Hello", "body": "You have a message", "data": {"key": "value"}}

Other: /push/subscribe, /push/unsubscribe, /push/send-to-topic, GET /push/logs

Feature Flags

Remote configuration and feature toggles. Permission: feature_flags

POST /api/v1/feature-flags

{"key": "dark_mode", "value": true, "description": "Enable dark mode", "is_active": true}

Other: GET /feature-flags, GET /feature-flags/{key}, DELETE /feature-flags/{key}

Link Preview

Fetch URL metadata (Open Graph). Permission: link_preview

GET /api/v1/link-preview?url={url}

{"data": {"title": "GitHub", "description": "...", "image_url": "...", "favicon_url": "...", "site_name": "GitHub"}}

Event Analytics

Track custom events and get summaries. Permission: analytics

POST /api/v1/analytics/track

{"event_name": "button_click", "event_category": "ui", "properties": {"button_id": "signup"}, "session_id": "sess_123"}

Other: POST /analytics/batch (max 100), GET /analytics/summary

IP Geolocation

Lookup IP geographic data. Permission: ip_geolocation

GET /api/v1/geoip/lookup?ip=8.8.8.8

{"data": {"ip": "8.8.8.8", "country": "US", "region": "California", "city": "Mountain View", "latitude": 37.386, "longitude": -122.084}}

Other: POST /geoip/batch, GET /geoip/me

Paste Bin

Create and share text snippets. Permission: paste_bin

POST /api/v1/pastes

{"content": "console.log('hello');", "title": "Snippet", "syntax": "javascript", "visibility": "public"}

Visibility: public, private, unlisted | GET /pastes/{id} public pastes need no auth

Encryption Vault

Store encrypted secrets. Permission: encryption_vault

POST /api/v1/vault

{"key": "stripe_secret", "value": "sk_live_xxx", "description": "Stripe API key"}

Other: GET /vault (keys only), GET /vault/{key}, DELETE /vault/{key}, POST /vault/encrypt, POST /vault/decrypt

Scheduled Tasks

Schedule one-time or recurring tasks. Permission: scheduled_tasks

POST /api/v1/scheduled-tasks

{"name": "Daily Report", "type": "webhook", "target_url": "https://example.com/report", "schedule_type": "recurring", "cron_expression": "0 9 * * *", "timezone": "UTC"}

OTP / Verification

Generate and verify OTP codes. Permission: otp

POST /api/v1/otp/send

{"identifier": "user@example.com", "purpose": "login"}

POST /api/v1/otp/verify

{"identifier": "user@example.com", "code": "123456", "purpose": "login"}

App Version Management

Check for app updates. Permission: app_version

GET /api/v1/app-versions/check?platform=android¤t_version=1.0.0

{"data": {"update_available": true, "force_update": false, "latest_version": "2.0.0", "changelog": "Bug fixes"}}

Other Services

Webhooks

POST /webhooks {url, secret, events[]} | GET/DELETE /webhooks/{id}

Audit Log

GET /audit-logs?action=x&date_from=x | GET /audit-logs/{id}

Data Export

POST /export/{csv,excel,json} {columns[], data[]}

Health Monitoring

POST /uptime-monitors {name, url, check_interval_minutes, alert_email}

Contact Form

POST /contact-form {name, email, subject, message}

Notification Center

POST /notifications {user_id, title, body, type} | PATCH /{id}/read

50+ Developer Utility Services

All utility endpoints follow the pattern: POST /api/v1/{category}/{action}

Format Converters

HTML/Markdown, JSON/CSV/XML/YAML, SVG to PNG/JPG

Hash & Encoding

MD5/SHA256, Base64, URL encode/decode

ID Generators

UUID v4/v7, ULID, NanoID, session tokens

Text & Content

Stats, keywords, sentiment, reading time, diff, lorem ipsum

Color Utilities

HEX/RGB/HSL conversion, contrast checker

Code Tools

Minify CSS/JS/HTML, format JSON/XML, regex test, cron parse

JWT & Security

JWT encode/decode/refresh, password strength, HTML sanitize

Network & DNS

DNS lookup, SSL check, user agent parse, robots.txt parse

Date, Time & Units

Timezone convert, business days, currency convert, unit convert

SEO & Web

Meta tags, sitemap XML, RSS feed, favicon, slug generator

Data Generators

Random strings/numbers/users/addresses, lorem ipsum

Developer Tools

SQL builder, GraphQL-to-REST, mock API, webhook debug, ASCII art

All 50+ utility services are accessible via API key with individual permission toggles. New API keys have all permissions enabled by default.

API Key Defaults

When creating a new project and API key, all permissions are enabled by default:

Can Read: Enabled (file listing, downloads, logs)
Can Write: Enabled (file uploads, deletions)
Can Send Emails: Enabled (email API access)
All Service Permissions: Enabled (70+ utility services)
Restricted: Disabled (no origin validation by default)
Default Email Daily Limit: 100 emails per account per day
Rate Limit: 60 requests/minute (customizable per key)

Rate Limits & Best Practices

Default: 60 requests/minute per API key
Batch operations: Max 100 items per request
Never hardcode API keys - use environment variables
Cache client instances - don't create per request
Implement retry logic with exponential backoff for 429 errors

AI Agent Integration Guide