API Reference

Sairo exposes a REST API that powers the web UI. All endpoints are available for programmatic use with the same authentication.

Authentication

All endpoints require authentication except:

• POST /api/auth/login — login
• GET /healthz — health check
• GET /api/share/{token} — public share link access

Authenticate with either:

• Session cookie — automatically set after login via the web UI
• Bearer token — pass an API token in the Authorization header:

Authorization: Bearer sairo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tip

Create API tokens from the web UI under API Tokens in the admin toolbar. Tokens have the same permissions as the user who created them.

Endpoint Reference

Auth

Method	Path	Description
POST	/api/auth/login	Log in with username and password
POST	/api/auth/logout	Log out and clear session cookie
GET	/api/auth/me	Get current user info
PUT	/api/auth/change-password	Change own password
POST	/api/auth/2fa/setup	Begin 2FA setup, returns QR code
POST	/api/auth/2fa/verify	Verify TOTP code to complete 2FA setup
POST	/api/auth/2fa/disable	Disable 2FA on own account
GET	/api/auth/users	List all users (admin only)
POST	/api/auth/users	Create a new user (admin only)
DELETE	/api/auth/users/{username}	Delete a user (admin only)
PUT	/api/auth/users/{username}	Update user (role, etc.) (admin only)
GET	/api/auth/users/{username}/permissions	Get per-bucket permissions (admin only)
PUT	/api/auth/users/{username}/permissions	Set per-bucket permissions (admin only)
DELETE	/api/auth/users/{username}/permissions/{bucket}	Remove bucket permission (admin only)
POST	/api/auth/2fa/reset/{username}	Reset a user’s 2FA (admin only)
POST	/api/auth/2fa/enable	Enable 2FA after setup verification
POST	/api/auth/2fa/recover	Log in with a recovery code
POST	/api/auth/refresh	Refresh session token
GET	/api/auth/tokens	List own API tokens
POST	/api/auth/tokens	Create a new API token
DELETE	/api/auth/tokens/{token_id}	Revoke an API token

OAuth & LDAP

Method	Path	Description
GET	/api/auth/oauth/providers	List available OAuth providers
GET	/api/auth/oauth/{provider}/login	Initiate OAuth flow (google or github)
GET	/api/auth/oauth/{provider}/callback	OAuth callback
POST	/api/auth/ldap	LDAP authentication

Buckets

Method	Path	Description
GET	/api/buckets	List all accessible buckets
POST	/api/buckets	Create a new bucket (admin only)
DELETE	/api/buckets/{bucket}	Delete an empty bucket (admin only)

Objects

Method	Path	Description
GET	/api/buckets/{bucket}/list	List objects at a prefix
GET	/api/buckets/{bucket}/download	Download an object via presigned URL redirect
POST	/api/buckets/{bucket}/upload	Upload a file
DELETE	/api/buckets/{bucket}/objects	Delete an object
DELETE	/api/buckets/{bucket}/folder	Delete a folder (prefix)
POST	/api/buckets/{bucket}/copy	Copy an object
POST	/api/buckets/{bucket}/rename	Rename an object
POST	/api/buckets/{bucket}/create-folder	Create a folder (empty prefix)
GET	/api/buckets/{bucket}/preview	Preview file content (first 500 KB)
GET	/api/buckets/{bucket}/presigned-url	Generate a presigned download URL
GET	/api/buckets/{bucket}/object-info	Get object metadata (size, ETag, etc.)
GET	/api/buckets/{bucket}/file-metadata	Get file metadata (Parquet/ORC/Avro schema)
GET	/api/buckets/{bucket}/preview-tail	Preview the tail of a file
GET	/api/buckets/{bucket}/folder-size	Get total size of a folder prefix
POST	/api/buckets/{bucket}/refresh-prefix	Refresh index for a specific prefix

Versions

Method	Path	Description
GET	/api/buckets/{bucket}/object-versions	Get versions for a specific object
GET	/api/buckets/{bucket}/list-versions	List all object versions in a bucket
POST	/api/buckets/{bucket}/version-restore	Restore a specific version
POST	/api/buckets/{bucket}/version-delete	Delete a specific version
POST	/api/buckets/{bucket}/purge-versions	Purge non-current versions
POST	/api/buckets/{bucket}/scan-versions	Scan for all versions in a bucket
GET	/api/buckets/{bucket}/version-presigned-url	Presigned URL for a specific version

Bucket Settings

Method	Path	Description
GET	/api/buckets/{bucket}/versioning	Get versioning status
PUT	/api/buckets/{bucket}/versioning	Enable or suspend versioning
GET	/api/buckets/{bucket}/lifecycle	Get lifecycle rules
PUT	/api/buckets/{bucket}/lifecycle	Set lifecycle rules
GET	/api/buckets/{bucket}/cors	Get CORS configuration
PUT	/api/buckets/{bucket}/cors	Set CORS configuration
GET	/api/buckets/{bucket}/acl	Get bucket ACL
PUT	/api/buckets/{bucket}/acl	Set bucket ACL
GET	/api/buckets/{bucket}/policy	Get bucket policy
PUT	/api/buckets/{bucket}/policy	Set bucket policy
GET	/api/buckets/{bucket}/tagging	Get bucket tags
PUT	/api/buckets/{bucket}/tagging	Set bucket tags
DELETE	/api/buckets/{bucket}/lifecycle	Delete lifecycle rules
DELETE	/api/buckets/{bucket}/cors	Delete CORS configuration
DELETE	/api/buckets/{bucket}/policy	Delete bucket policy
GET	/api/buckets/{bucket}/website	Get bucket website configuration
GET	/api/buckets/{bucket}/location	Get bucket location

Object Settings

Method	Path	Description
GET	/api/buckets/{bucket}/object-acl	Get object ACL
PUT	/api/buckets/{bucket}/object-acl	Set object ACL
GET	/api/buckets/{bucket}/object-tagging	Get object tags
PUT	/api/buckets/{bucket}/object-tagging	Set object tags
DELETE	/api/buckets/{bucket}/object-tagging	Delete object tags
GET	/api/buckets/{bucket}/object-lock	Get object lock configuration
GET	/api/buckets/{bucket}/object-retention	Get object retention policy
GET	/api/buckets/{bucket}/object-legal-hold	Get object legal hold status

Multipart Uploads

Method	Path	Description
GET	/api/buckets/{bucket}/multipart-uploads	List in-progress multipart uploads
POST	/api/buckets/{bucket}/abort-multipart	Abort a multipart upload

Analytics

Method	Path	Description
GET	/api/buckets/{bucket}/storage-breakdown	Get storage breakdown by prefix
GET	/api/buckets/{bucket}/storage-history	Get storage growth over time

Search

Method	Path	Description
GET	/api/buckets/{bucket}/search?q={term}	Full-text search within a bucket

Index

Method	Path	Description
GET	/api/buckets/{bucket}/crawl-status	Get indexing status for a bucket
POST	/api/buckets/{bucket}/crawl	Trigger a reindex of a bucket

Share Links

Method	Path	Description
GET	/api/share-links	List all share links (admin only)
POST	/api/share-links	Create a new share link
DELETE	/api/share-links/{link_id}	Delete a share link
GET	/api/share/{token}	Access a shared file (public, no auth)

Audit Log

Method	Path	Description
GET	/api/audit-log	Get audit log entries (admin only)

Endpoints (Multi-S3)

Method	Path	Description
GET	/api/endpoints	List configured S3 endpoints
POST	/api/endpoints	Add a new S3 endpoint (admin only)
PUT	/api/endpoints/{id}	Update an S3 endpoint (admin only)
DELETE	/api/endpoints/{id}	Remove an S3 endpoint (admin only)
POST	/api/endpoints/{id}/test	Test endpoint connection (admin only)
GET	/api/all-buckets	List buckets across all endpoints

License

Method	Path	Description
GET	/api/license	Get license info
POST	/api/license	Activate a license key (admin only)

Health & System

Method	Path	Description
GET	/healthz	Health check (no auth required)
GET	/api/branding	Get branding configuration
GET	/api/health-detail	Detailed health with S3, DB, and crawler status
GET	/api/health/s3	S3 connectivity check
POST	/api/health/s3/refresh	Refresh S3 health check
GET	/api/system-info	System information