API overview

The FilesHub API lives under /api/v1 and is authenticated with an X-API-Key header. File objects are the surface most apps integrate first, but the same base URL and key also cover transactional email, background jobs, and 40+ developer utilities.

Base URL

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

Two status endpoints live one level up, at /api (not /api/v1): /health and /version.

Authentication & scopes

Send X-API-Key: <key> on every request. A key is per project and carries scopes:

Scope	Grants
read	List and read (download private objects, list jobs/templates/schedules).
write	Create and delete (upload, delete, manage schedules/templates).
email	Send email (can_send_emails).
email_template	Manage email templates (with write).
service scopes	Per-utility access (e.g. converter, qr_code) — all enabled by default.

Keys can also be restricted to your own web origins or apps so you can ship one in a frontend — see Authentication and API key restrictions.

Object endpoints

Method	Path	Permission	Purpose
POST	/objects	write	Upload an object (multipart file).
GET	/objects/{public_id}	none (public) / read (private)	Download / view an object (streams the file).
GET	/objects	read	List objects (paginated).
DELETE	/objects/{public_id}	write	Delete an object.

Email endpoints

Method	Path	Permission	Purpose
POST	/emails/send	email	Send an email (raw or template; queued by default).
GET	/emails/templates	read	List templates.
POST/PATCH/DELETE	/emails/templates{/slug}	write + email_template	Manage templates.
GET/POST/PATCH/DELETE	/email-schedules{/id}	read/write	Recurring schedules.
POST	/email-schedules/{id}/run	write	Run a schedule now.

Jobs & status

Method	Path	Permission	Purpose
GET	/jobs · /jobs/{job_id}	read	Poll queued operations.
GET	/api/health	none	Health check (no key).
GET	/api/version	none	Deploy-version marker (no key).

Beyond these, 40+ stateless developer utilities and the stateful platform services share the same base URL and key.

The object shape

An object returned by the API has these fields (exact set varies by endpoint):

Field	Type	Notes
public_id	string (ULID)	Stable, URL-safe, sortable id. Used in the object URL.
project_id	string (ULID)	The owning project's public id.
original_filename	string	The filename you uploaded.
mime_type	string	Detected on upload (e.g. image/png).
size_bytes	integer	File size in bytes.
visibility	public | private	Access control — see File visibility.
url	string	The full download/view URL for the object.
expires_at	string (ISO-8601) | null	When the object auto-deletes, if an expiry was set.
created_at	string (ISO-8601)	Upload time (returned by the list endpoint).

Conventions

• Content type — uploads are multipart/form-data; all JSON responses are application/json.
• Identifiers — objects are addressed by their ULID public_id, never by an internal numeric id.
• Errors — failures return { "message": "..." } with an appropriate status code. See Errors & limits.
• Versioning — the path is versioned (/api/v1); future breaking changes ship under /api/v2.

Read the per-endpoint pages for exact parameters, examples, and every response and error body.

Machine-readable

• OpenAPI 3.1 spec — /openapi.json covers objects, emails, jobs, schedules, templates, and version/health for AI agents and codegen.
• Raw Markdown — every doc page is mirrored under /raw/ (index: /raw/manifest.json) so an agent can load the docs into its context.