AI Integration Guide

Download for AI Agents

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

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

Available Services (22 Total)

Service	Permission	Key Endpoints
File Storage	`read`, `write`	POST/GET/DELETE /objects
Email	`email`	POST /emails/send, GET /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

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