Apps Overview

Looking for the product view?

The Help Center explains this surface as users see it: Managing an App.

Apps are AI-powered interactive applications that combine custom HTML, CSS, and JavaScript with access to Informer datasets and AI capabilities.

Key Concepts

Two tiers, one API: every App row has a type that picks its tier driver. report is a Magic Report, available on every tenant; app is a full App, which requires the Apps license and unlocks the full manifest surface (access: whitelists, integration dependencies, agents). The tier also sets the role floors: most write operations need Designer on a Magic Report but Admin on a full App. Upgrading report → app is allowed (license + role gated); downgrading is refused.

Draft/Edit Workflow: Apps use a draft-based editing model with one draft per app and an edit lock:

Opening a draft (POST /apps/{id}/_edit) creates the draft, or returns the existing one with its lock state
Changes to drafts don't affect the published version
Committing a draft (POST /apps/{id}/draft/_commit) publishes changes
Discarding a draft (DELETE /apps/{id}/draft) abandons changes

Library-Based Storage: Each app has an associated Library that stores its files (HTML, CSS, JavaScript, images, etc.). Files are accessed through the /contents/ routes.

Access Control: Apps support:

Team-based ownership
Share-based access (via AppShare model)
Token-based external sharing
Tiered permission floors (see the Permissions table below)
Custom roles via informer.yaml for app-specific access control

Common Workflows

Creating an App

// 1. Create the app
POST /api/apps
{
  "type": "report",
  "name": "Sales Dashboard",
  "description": "Interactive sales analytics",
  "datasets": [
    {
      "datasetId": "abc-123",
      "alias": "sales",
      "label": "Sales Data"
    }
  ]
}

// 2. Add files to the app's library
PUT /api/apps/{id}/contents/index.html
{
  "content": "<html>...</html>",
  "contentType": "text/html"
}

Editing an App

// 1. Create a draft
POST /api/apps/{id}/_edit
// Returns the draft app with editingId = {id}

// 2. Modify draft files
PUT /api/apps/{draftId}/contents/index.html
{
  "content": "<html>Updated...</html>"
}

// 3. Commit the draft
POST /api/apps/{id}/draft/_commit
// Publishes changes to original app, deletes draft

// Or discard
DELETE /api/apps/{id}/draft
// Deletes draft without affecting original

// Share with a team
PUT /api/apps/{id}/shares/marketing
{
  "accessLevel": 1
}

// Get all shares
GET /api/apps/{id}/shares

// Check data access requirements
GET /api/apps/{id}/data-access

API Endpoints

The Apps API is organized into several functional areas:

Core CRUD - List, create, retrieve, update, delete apps
Draft Management - Draft-based editing workflow
File Management - Upload, read, write, patch app files
Ownership & Sharing - Owner management and share permissions
Tags - Tag assignment and management
Tokens - External sharing via tokens
Actions - Copy, print, and other operations
Roles - Custom role definitions and resolution
Server Routes - Server-side route handlers (sandboxed V8)
Persistence - Dedicated Postgres workspace and migrations
Embeddings - Declarative vector embeddings: the embeddings/ folder, the platform pump, and the status/run routes
Usage Stats - View counts, API invocation history, and workspace storage
Embedded Chat - Per-user AI copilot chat sessions
AI Suggestions - Data-driven and AI-powered app creation suggestions
Agents - AI agents with event-driven execution, cron scheduling, and tool calling
Messages - Push notification and email delivery queue with retry and history
Webhooks - Public webhook endpoints for external service callbacks
Channels - Live channels an App pushes to its open pages, and their counters
Dependencies - Typed dependency slots, bindings, and the OpenAPI discovery document
MCP - The App's Model Context Protocol endpoint and the MCP-apps directory
Runtime - The view/launch surfaces, API proxy, icons, and always-blocked endpoints
Environment - Environment variables and secrets
Databases - External Postgres connection profiles (superuser)

Key Concepts

Custom Roles: Apps can define custom roles in informer.yaml that go beyond the standard team permission levels. Roles are assigned via shares and checked in both client-side code and server route handlers. See Roles.

Server Routes: Files in the server/ directory define server-side handlers that run in sandboxed V8 isolates. Handlers can query the app's Postgres workspace and make authenticated API calls. See Server Routes.

Webhooks: Files in the webhooks/ directory define public endpoints that external services can call without authentication. Webhook handlers run with the app owner's credentials. See Webhooks.

Persistence: Each app can have a dedicated Postgres schema for storing custom data. SQL migrations in migrations/ are run during deploy. Server route handlers access this data via the query() callback. See Persistence.

Embeddings: Files in the embeddings/ directory declare vector-embedding use cases over the app's own workspace data. The platform pump asks the app what is pending, chunks and embeds it in billed batches, and hands the vectors back for the app to store; embed(name, text) gives handlers query-time vectors from the same model, returning { embedding, revision } so a query can restrict itself to rows in its own vector space. See Embeddings.

AI Agents: Apps can define autonomous AI agents in informer.yaml that respond to events, run on cron schedules, and call app tools and external toolkits. See Agents.

HAL Relations

Apps expose the following HAL relations:

Relation	Description
`inf:app`	Link to a single app
`inf:apps`	Link to the apps collection
`inf:apps-list`	Link to the flat apps list
`inf:owner`	Link to the app's owner
`inf:draft`	Link to the user's draft of this app
`inf:app-shares`	Link to all shares
`inf:app-share`	Templated link to a specific share (by principalId)
`inf:app-roles`	Link to app role definitions
`inf:app-tags`	Link to app tags
`inf:app-tag`	Templated link to a specific tag assignment (by tagId)
`inf:app-tokens`	Link to app tokens
`inf:favorite`	Toggle favorite status
`inf:copy`	Copy the app
`inf:print`	Export app as PDF (array with two entries)
`inf:export-bundle`	Export app bundle
`inf:cloud-publish`	Publish app to cloud
`inf:apps-recent`	Link to recently viewed apps
`inf:apps-drafts`	Link to the user's drafts across all apps
`inf:app-suggestions`	Link to keyword-based app suggestions
`inf:app-suggestions-ai`	Link to AI-powered app suggestions
`inf:app-chat`	Link to the app's embedded copilot chat
`inf:app-stats`	Link to app usage statistics
`inf:app-stats-tables`	Link to app workspace table listing
`inf:app-stats-api`	Link to app API invocation history
`inf:app-agents`	Link to app agent listing
`inf:app-messages`	Link to app message delivery queue
`inf:app-webhooks`	Link to app webhook routes and stats
`inf:app-channels`	Link to the app's live channels, limits, and counters
`inf:app-embeddings`	Link to app embedding use cases and their pump status
`inf:app-embedding-run`	Templated link to run one embedding use case now (by name)
`inf:app-embedding-embed`	Templated link to embed one text through a use case's model (by name) — what the vite plugin's dev mirror calls for `embed()`
`inf:app-dependencies`	Link to the app's dependency slots
`inf:app-dependency`	Templated link to one dependency slot (by name)
`inf:app-mcp`	The app's MCP endpoint
`inf:mcp-apps`	Directory of MCP-enabled apps
`inf:app-openapi`	The app's OpenAPI discovery document
`inf:app-icon`	The app's gallery/browser-tab icon
`inf:app-unmanage`	Release a managed app back to UI editing
`inf:app-workspace-query`	Run management SQL against the workspace
`inf:app-workspace-query-history`	Audited workspace query history
`inf:app-workspace-backup`	Download a portable workspace data backup
`inf:app-workspace-restore`	Restore a workspace data backup
`inf:entrypoint`	Link to the app's view entry point (single app only)
`inf:library`	Link to the app's file library (single app only)
`inf:library-contents`	Link to raw library contents (single app only)
`edit`	Edit the app (create a draft)
`share`	Templated share page URL (with token placeholder)

Permissions

Apps use a team role-based permission system. The write floor is owned by the tier driver: Designer for Magic Reports (type: report), Admin for full Apps (type: app).

Permission	Required Role	Usage
`create`	Designer (report) / Admin (app)	Create new apps; the license gate runs first
`run`	Member	View and execute apps
`write`	Designer (report) / Admin (app)	Mutate the app row, files, deploy
`edit`	write and not managed	UI editing (drafts, manifest, identity); refused on deployed/marketplace apps
`manage`	Same as write	Open the admin panel (managed apps included)
`delete` / `restore` / `copy`	Same as write	Lifecycle operations
`purge`	Data Wizard	Irreversibly destroy a soft-deleted app
`bind`	Member+	Bind dependency slots and set environment values (installer surface)
`share`	Publisher or Superuser	Share apps with teams/users
`assignTags`	Designer	Assign tags to apps
`changeOwner`	Admin or Superuser	Transfer app ownership

Model Structure

An App has the following key fields:

{
  id: string;              // UUID
  type: string;            // App driver type (e.g., "report")
  name: string;            // Display name
  slug?: string;           // URL-friendly identifier
  ownerId: string;         // Principal ID of owner
  naturalId: string;       // ownerId:slug or id (computed)
  description?: string;    // Optional description
  defn: object;            // App definition (driver-specific)
  settings: object;        // App settings
  libraryId?: string;      // Associated library UUID
  editingId?: string;      // If this is a draft, ID of original
  shared: boolean;         // Whether app is shared
  defnUpdatedAt?: Date;    // Last app-definition change (e.g. draft commit)
  contentModifiedAt?: Date | null;  // Derived (not stored): MAX(modifiedAt) across the app's library files; null if none. File edits do not write the app row.
  createdAt: Date;
  updatedAt: Date;         // Last write to the app row itself (not file edits)
}

Search and Discovery

Apps integrate with the global search and report-list systems:

They appear in /api/reports-list alongside other report types
They have a search driver (app) for global search
They appear in the "New > Reports" menu when the ai feature is enabled

Key Concepts​

Common Workflows​

Creating an App​

Editing an App​

Sharing an App​

API Endpoints​

Key Concepts​

HAL Relations​

Permissions​

Model Structure​

Search and Discovery​

Key Concepts

Common Workflows

Creating an App

Editing an App

Sharing an App

API Endpoints

Key Concepts

HAL Relations

Permissions

Model Structure

Search and Discovery