Apps API

The Apps API allows you to manage applications within your tenant. Each app is a container for datatables, functions, and other resources.

Endpoints

Method	Endpoint	Description
GET	`/api/apps/`	List all apps
GET	`/api/apps/{slug}/`	Get app details
POST	`/api/apps/`	Create a new app
PUT	`/api/apps/{slug}/`	Update an app
PATCH	`/api/apps/{slug}/`	Partially update an app
DELETE	`/api/apps/{slug}/`	Soft delete an app

List Apps

Get a list of all apps in the current tenant.

GET /api/apps/

Response:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Analytics App",
      "slug": "analytics-app",
      "description": "Analytics and reporting application",
      "table_count": 5,
      "settings": {
        "display_name": "Analytics Dashboard",
        "category": "analytics",
        "icon_url": "https://api.example.com/media/app_settings/icons/analytics.png",
        "primary_color": "#1976d2"
      },
      "created_at": "2025-12-12T10:00:00Z",
      "updated_at": "2025-12-12T10:00:00Z"
    }
  ],
  "total": 1
}

Get App Details

Get detailed information about a specific app.

GET /api/apps/{slug}/

Response:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "id": 1,
    "name": "Analytics App",
    "slug": "analytics-app",
    "description": "Analytics and reporting application",
    "table_count": 5,
    "tables": [
      {
        "id": 1,
        "name": "users",
        "provider_type": "flat_table",
        "is_materialized": true,
        "physical_table_name": "analytics_app_users"
      }
    ],
    "settings": {
      "id": 1,
      "display_name": "Analytics Dashboard",
      "icon": "app_settings/icons/analytics.png",
      "icon_url": "https://api.example.com/media/app_settings/icons/analytics.png",
      "primary_color": "#1976d2",
      "secondary_color": "#dc004e",
      "banner_image": null,
      "banner_image_url": null,
      "category": "analytics",
      "max_functions": 100,
      "max_datatables": 50,
      "rate_limit_per_hour": 1000,
      "documentation_url": "https://docs.example.com",
      "support_email": "[email protected]",
      "default_frontend_worker": null,
      "default_frontend_worker_details": null,
      "created_at": "2025-12-12T10:00:00Z",
      "updated_at": "2025-12-12T10:00:00Z"
    },
    "created_at": "2025-12-12T10:00:00Z",
    "updated_at": "2025-12-12T10:00:00Z",
    "created_by": 1,
    "modified_by": null
  }
}

Create App

Create a new app with optional settings.

POST /api/apps/
Content-Type: application/json

{
  "name": "My New App",
  "description": "Application description",
  "settings": {
    "display_name": "Custom Display Name",
    "primary_color": "#ff0000",
    "category": "analytics",
    "max_functions": 200
  }
}

Response:

{
  "status": "success",
  "message": "App created successfully",
  "data": {
    "id": 2,
    "name": "My New App",
    "slug": "my-new-app",
    "description": "Application description",
    "table_count": 0,
    "tables": [],
    "settings": {
      "id": 2,
      "display_name": "Custom Display Name",
      "icon": null,
      "icon_url": null,
      "primary_color": "#ff0000",
      "secondary_color": "#dc004e",
      "banner_image": null,
      "banner_image_url": null,
      "category": "analytics",
      "max_functions": 200,
      "max_datatables": 50,
      "rate_limit_per_hour": 1000,
      "documentation_url": "",
      "support_email": "",
      "default_frontend_worker": null,
      "default_frontend_worker_details": null,
      "created_at": "2025-12-12T11:00:00Z",
      "updated_at": "2025-12-12T11:00:00Z"
    },
    "created_at": "2025-12-12T11:00:00Z",
    "updated_at": "2025-12-12T11:00:00Z",
    "created_by": 1,
    "modified_by": null
  }
}

Create App Without Settings

If you don't provide settings, default values are used:

POST /api/apps/
Content-Type: application/json

{
  "name": "Simple App",
  "description": "App with default settings"
}

The app will be created with:

display_name: Same as app name ("Simple App")
primary_color: #1976d2 (default blue)
secondary_color: #dc004e (default pink)
category: analytics (default)
max_functions: 100 (default)
max_datatables: 50 (default)
rate_limit_per_hour: 1000 (default)

Update App

Update an app's basic information (name, description).

PUT /api/apps/{slug}/
Content-Type: application/json

{
  "name": "Updated App Name",
  "description": "Updated description"
}

Note: To update app settings, use the App Settings API endpoints (documented below in the App Settings section).

Delete App

Soft delete an app (marks as inactive).

DELETE /api/apps/{slug}/

Response:

{
  "status": "success",
  "message": "App deleted successfully"
}

Settings in Response

List View (Lightweight)

When listing apps, only essential settings are included:

display_name
category
icon_url
primary_color

Detail View (Complete)

When retrieving a single app, complete settings are included with all fields.

See the App Settings section below for managing app settings and configurations.

Notes

App slugs are auto-generated from the name
Settings are automatically created when an app is created
Deleting an app is a soft delete (marks as inactive)
All datatables associated with a deleted app are also marked as inactive

App Settings

App Settings provide per-app configuration for branding, technical limits, and metadata. Each app can have customized settings including theme colors, icons, banners, resource limits, and documentation links.

Nested Under Apps

All app settings endpoints are nested under the app: /api/apps/{app_slug}/settings/. Each app has exactly one settings configuration.

App Settings Endpoints

Method	Endpoint	Description
GET	`/api/apps/{app_slug}/settings/`	Get app settings
POST	`/api/apps/{app_slug}/settings/`	Create app settings (not recommended - auto-created)
PUT	`/api/apps/{app_slug}/settings/`	Full update app settings
PATCH	`/api/apps/{app_slug}/settings/`	Partial update app settings
DELETE	`/api/apps/{app_slug}/settings/`	Not allowed

Settings Overview

App Settings enable you to configure individual apps with:

Branding: Custom colors, icons, and banner images
Categorization: Organize apps by type (Analytics, Integration, Storage)
Resource Limits: Control maximum functions, datatables, and API rate limits
Documentation: Link to app-specific docs and support contacts
Frontend Worker: Set default frontend worker URL

Key Features

Automatic Creation

Settings are automatically created when you create an app:

No need to manually create settings - they're auto-generated with defaults
Each app gets one settings configuration
Settings cannot be deleted (only updated)
Default values are applied automatically (display name = app name, default colors, etc.)

Custom Settings on App Creation

You can provide custom settings when creating an app:

POST /api/apps/
{
  "name": "My App",
  "description": "App description",
  "settings": {
    "display_name": "Custom Display Name",
    "primary_color": "#ff0000",
    "category": "analytics"
  }
}

Configuration Options

Display & Branding

Field	Type	Required	Default	Description
`display_name`	string	No	""	Display name for the app (max 255 chars)
`icon`	file	No	null	App icon (max 5MB)
`primary_color`	string	No	"#1976d2"	Primary theme color (hex format)
`secondary_color`	string	No	"#dc004e"	Secondary theme color (hex format)
`banner_image`	file	No	null	Banner/hero image (max 5MB)

Metadata

Field	Type	Required	Default	Description
`category`	string	No	"analytics"	App category (analytics, integration, storage)

Technical Limits

Field	Type	Required	Default	Description
`max_functions`	integer	No	100	Maximum functions allowed
`max_datatables`	integer	No	50	Maximum datatables allowed
`rate_limit_per_hour`	integer	No	1000	API rate limit per hour

Documentation

Field	Type	Required	Default	Description
`documentation_url`	string (URL)	No	""	Link to app documentation
`support_email`	string (email)	No	""	Support contact email

Frontend Worker

Field	Type	Required	Default	Description
`default_frontend_worker_url`	string (URL)	No	null	Read-only URL to default frontend worker

Get App Settings

GET /api/apps/{app_slug}/settings/
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "success": true,
  "message": "App settings retrieved successfully",
  "data": {
    "display_name": "My Analytics App",
    "icon": "/media/app_settings/icons/icon_abc123.png",
    "icon_url": "http://localhost:8000/media/app_settings/icons/icon_abc123.png",
    "primary_color": "#1976d2",
    "secondary_color": "#dc004e",
    "banner_image": "/media/app_settings/banners/banner_xyz789.jpg",
    "banner_image_url": "http://localhost:8000/media/app_settings/banners/banner_xyz789.jpg",
    "category": "analytics",
    "max_functions": 100,
    "max_datatables": 50,
    "rate_limit_per_hour": 1000,
    "documentation_url": "https://docs.example.com",
    "support_email": "[email protected]",
    "default_frontend_worker_url": "https://my-app.example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Update App Settings

Update specific fields only:

PATCH /api/apps/{app_slug}/settings/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "max_functions": 300,
  "rate_limit_per_hour": 3000
}

Upload Files

Upload icon or banner image using multipart form data:

curl -X PATCH "http://localhost:8000/api/apps/my-analytics-app/settings/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "icon=@/path/to/icon.png" \
  -F "primary_color=#ff0000"

Set Default Frontend Worker

PATCH /api/apps/{app_slug}/settings/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "default_frontend_worker": 123
}

The response will include default_frontend_worker_url with the full URL.

Validation Rules

Color Validation

Must be valid hex color format: #RRGGBB
Examples: #1976d2, #FFFFFF, #000000

Number Validation

max_functions, max_datatables, rate_limit_per_hour must be >= 0

File Validation

Max Size: 5MB per file
Allowed Formats: png, jpg, jpeg, svg, ico, webp, gif

Category Validation

Must be one of: analytics, integration, storage

Frontend Worker Validation

Worker must belong to the same app
Can be set to null to clear the default worker

Field Exclusions

The following fields are intentionally excluded from API responses:

id: Apps and settings use slug as the primary identifier
default_frontend_worker: Only the URL is returned (write-only for updates)

Performance Considerations

List vs Detail Views

List View: Returns lightweight settings (4 fields) for better performance
Detail View: Returns complete settings (all fields) for full information

Caching

App settings are frequently accessed and should be cached at the application level for optimal performance.

Endpoints​

List Apps​

Get App Details​

Create App​

Create App Without Settings​

Update App​

Delete App​

Settings in Response​

List View (Lightweight)​

Detail View (Complete)​

Related Endpoints​

Notes​

App Settings

App Settings Endpoints​

Settings Overview​

Key Features​

Automatic Creation​

Custom Settings on App Creation​

Configuration Options​

Display & Branding​

Metadata​

Technical Limits​

Documentation​

Frontend Worker​

Get App Settings​

Update App Settings​

Upload Files​

Set Default Frontend Worker​

Validation Rules​

Color Validation​

Number Validation​

File Validation​

Category Validation​

Frontend Worker Validation​

Field Exclusions​

Performance Considerations​

List vs Detail Views​

Caching​

Endpoints

List Apps

Get App Details

Create App

Create App Without Settings

Update App

Delete App

Settings in Response

List View (Lightweight)

Detail View (Complete)

Related Endpoints

Notes

App Settings Endpoints

Settings Overview

Key Features

Automatic Creation

Custom Settings on App Creation

Configuration Options

Display & Branding

Metadata

Technical Limits

Documentation

Frontend Worker

Get App Settings

Update App Settings

Upload Files

Set Default Frontend Worker

Validation Rules

Color Validation

Number Validation

File Validation

Category Validation

Frontend Worker Validation

Field Exclusions

Performance Considerations

List vs Detail Views

Caching