RESTful API

Introduction

The Fairu RESTful API provides programmatic access to your digital assets, folders, galleries, and more. Use it to build integrations, automate workflows, or sync Fairu with your existing systems.

Interactive documentation

Explore the complete API reference with interactive examples at:

fairu.app/restful/docs

The interactive documentation allows you to:

• Browse all available endpoints
• See request and response schemas
• Test API calls directly in your browser

Authentication

The RESTful API uses Bearer token authentication. Include your API token in the Authorization header of every request.

curl -X GET "https://fairu.app/restful/health" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Obtaining an API token

1. Navigate to Settings → API Tokens in your Fairu dashboard
2. Click Create token
3. Give your token a descriptive name
4. Select the required permissions (abilities)
5. Copy and securely store your token

API tokens are scoped to specific abilities like file::view, file::create, folder::read, etc.

Base URL

All API requests should be made to:

https://fairu.app/restful

Available resources

The API provides CRUD operations for all major Fairu resources:

• Files – Upload, retrieve, update, search, and delete files
• Folders – Create and manage folder structures
• Galleries – Create and share image galleries
• Copyrights – Manage copyright information
• Licenses – Track and assign licenses
• Workflows – Automate file processing
• Users & Roles – Manage team access
• Disks – Configure sync disk connections

See the interactive documentation for detailed endpoint specifications.

Response format

All responses are returned as JSON.

Pagination

List endpoints support pagination with page and per_page parameters:

GET /restful/files?page=2&per_page=50

Error responses

Errors return appropriate HTTP status codes with details:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Best practices

• Use appropriate scopes – Only request the token abilities you need
• Handle pagination – Always paginate through large result sets
• Cache responses – Cache data that doesn't change frequently

SDKs

We provide official SDKs to make integrating with the Fairu API easier:

fairu.app/sdk

The SDKs handle authentication, request formatting, and error handling for you.

Need help?

• Interactive docs: fairu.app/restful/docs
• SDKs: fairu.app/sdk
• GraphQL API: For more complex queries, consider using our GraphQL API
• Support: Contact us via the support form in your dashboard