AI Suggestions

Endpoints for generating app creation suggestions based on available data sources and AI analysis.

GET /api/apps/suggestions

Get keyword-based app suggestions derived from the user's available datasets and toolkits.

Authentication: Required

Pre-requisites: AI feature must be enabled (ai.verify)

Response:

{
  "suggested": [
    {
      "label": "Sales Dashboard",
      "description": "Track revenue, orders, and sales performance",
      "prompt": "Create a sales dashboard that shows revenue trends...",
      "icon": "trending_up",
      "color": "green"
    }
  ],
  "templates": [
    {
      "id": "kpi-dashboard",
      "title": "KPI Dashboard",
      "description": "Track key performance indicators with live metrics",
      "icon": "speed",
      "color": "blue",
      "category": "template",
      "prompt": "Create a KPI dashboard that..."
    }
  ],
  "meta": {
    "source": "keyword-based",
    "datasetsAnalyzed": 5,
    "toolkitsAnalyzed": 2
  }
}

Key Fields:

Field	Description
suggested	Data-driven suggestions based on dataset field names and toolkit types
templates	Static template suggestions (KPI dashboard, data explorer, etc.)
meta.source	Always "keyword-based" for this endpoint
meta.datasetsAnalyzed	Number of datasets analyzed for pattern matching

Pattern Matching:

Suggestions are generated by matching keywords in dataset field names against known patterns (sales, customer, inventory, employee, finance, project, shipping) and toolkit types (GitHub, Slack, Stripe, Jira, Salesforce).

---

POST /api/apps/suggestions

Generate AI-powered app suggestions using an LLM to analyze available data sources.

Authentication: Required

Pre-requisites: AI feature must be enabled (ai.verify)

Payload: None (empty body)

Response:

{
  "suggestions": [
    {
      "label": "Sales Performance Tracker",
      "description": "Monitor revenue trends and team performance with interactive charts",
      "prompt": "Create an interactive sales dashboard using the Orders dataset...",
      "icon": "trending_up",
      "color": "green"
    }
  ],
  "meta": {
    "source": "ai",
    "datasetsAnalyzed": 5,
    "queriesAnalyzed": 3,
    "datasourcesAnalyzed": 2
  }
}

Key Fields:

Field	Description
suggestions	AI-generated suggestions with detailed prompts referencing specific data sources
meta.source	Always "ai" for this endpoint

Behavior:

• Loads up to 10 each of the user's datasets, queries, and datasources to build context
• Uses an LLM to generate relevant app suggestions with specific prompts
• Falls back to keyword-based suggestions if the AI call fails
• Suggestions include detailed prompts that reference the user's actual data sources

POST /api/apps/{id}/_suggest-icon

Generate a duotone SVG favicon for a specific app, optionally refining across multiple iterations within the same dialog session.

Authentication: Required.

Permission: permission.app.edit (Member+, level 2 + not managed). Editing the favicon is an identity mutation, locked on managed apps.

Pre-requisites: AI feature must be enabled. The strategic-tier model (go_strategic) must be registered.

Payload: all optional.

{
  "name":        "Optional name override (defaults to app.name)",
  "description": "Optional description override",
  "refine":      "Free-text note for next iteration (e.g. 'more blue, less busy')",
  "previousSvg": "<svg>...</svg>",
  "metaphor":    "shopping-bag"
}

• refine is folded into the prompt as "the user asked for these changes." Capped at 500 characters server-side.
• previousSvg is the most-recent suggestion the dialog received; the model uses it as the "previous design" it iterates on. First-pass calls (no previous SVG) design from scratch.
• metaphor is a Font Awesome icon NAME (no fa- prefix) used as inspiration for the central glyph. The server passes the name only, not the path data, so the model redraws at app-tile scale rather than pasting the literal icon onto a tile.

Response:

{ "svg": "<svg ...>...</svg>" }

The server validates the SVG before returning: must start with <svg, must not contain <image> / <script> / href (executable or external-asset hooks), and must be ≤ 32 KB. Validation failures return a clear error message — see app/lib/favicon-design.md for the design constraints the model is asked to follow.

Errors:

Status	Cause
403	App is managed (origin: deployed/marketplace) — favicon is publisher-locked.
503	go_strategic model unavailable.
422	Generated SVG failed the content-safety whitelist (<script> etc.).