Skip to main content
POST
Create an App

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to create a new App.

Only slug and meta are required. After creation, deploy a zip bundle via POST /v1/apps/{app_id}/deploy.

Legacy page-builder fields (template, sections, custom_html, hero, theme, seo, stats, featured_gallery, tabs, password_secret_name) are accepted for backward compatibility but deprecated. New apps should not use them.

slug
string
required

URL-safe slug (globally unique, lowercase + hyphens). Becomes your URL: {slug}.mxp.co

Required string length: 3 - 60
Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Examples:

"my-product-search"

"brand-dashboard"

meta
PageMeta · object
required

App metadata (title, logo, favicon)

auth_config
AuthConfig · object | null

End-user authentication. Set mode='clerk' for managed auth.

build_config
BuildConfig · object | null

JSX build configuration for an App.

Phase 1: schema only. Phase 3: used by the build pipeline Celery task.

monitoring_config
MonitoringConfig · object | null

Opt-in monitoring configuration for a Canvas app.

All monitoring is off by default except error_boundary_enabled, which is a client-side UX safety net (shows fallback UI instead of blank page) and sends no data externally.

When sentry_enabled or posthog_enabled are turned on, monitoring data is sent to Mixpeek-internal Sentry/PostHog — never to the customer's own observability stack. PII is stripped via beforeSend / mask_all_text, and session replay is always off.

is_active
boolean
default:true
template
string
default:generic
deprecated
sections
SectionConfig · object[]
deprecated
custom_html
string | null
deprecated
hero
HeroConfig · object | null
deprecated

Hero section configuration for a page.

theme
ThemeConfig · object
deprecated

Theme configuration for public retriever UI.

Defines colors, fonts, and visual styling for the public search interface.

seo
SEOConfig · object | null
deprecated

SEO configuration for public retriever discoverability.

Auto-generated during publishing with sensible defaults inferred from the retriever's display_config. All fields can be overridden manually.

This configuration controls how the public retriever appears in:

  • Search engine results (Google, Bing, etc.)
  • Social media shares (Twitter, Facebook, LinkedIn)
  • Link previews in messaging apps
Example:
stats
StatItem · object[]
deprecated

Configuration for the featured gallery section.

tabs
PageTab · object[]
deprecated
password_secret_name
string | null
deprecated

Response

The created App configuration

Response model for an App.

Deploy-based apps use versions, environments, build_config, and auth_config. Legacy page-builder fields (template, sections, custom_html, hero, theme, seo, stats, featured_gallery, tabs, password_protected) are included for backward compatibility but deprecated.

app_id
string
required
slug
string
required
url
string
required

Canonical published URL (https://{slug}.mxp.co)

meta
PageMeta · object
required

Page-level metadata (REQUIRED when creating a page).

This object is separate from the optional seo field. meta controls the visible page chrome (browser tab title, logo, favicon), while seo controls search-engine tags (og:title, og:description, etc.).

is_active
boolean
required
version
integer
required
custom_domains
CustomDomainConfig · object[]
required
auth_config
AuthConfig · object | null
required

End-user authentication configuration for an App.

Supported modes:

  • public: No authentication required (default)
  • clerk: Managed auth via Clerk Organizations — handles Google, GitHub, email/password signup/login. Each canvas app maps to a Clerk Organization. Users are synced to canvas_users via Clerk webhooks.
  • password: Simple password gate — visitors must enter a password to access the app. The password is hashed (bcrypt) before storage.
  • api_key, jwt, sso_oidc, sso_saml: Advanced modes retained for future use.
build_config
BuildConfig · object | null
required

JSX build configuration for an App.

Phase 1: schema only. Phase 3: used by the build pipeline Celery task.

environments
Environments · object
required
created_at
string<date-time> | null
required
updated_at
string<date-time> | null
required
template
string
required
deprecated
sections
SectionConfig · object[]
required
deprecated
custom_html
string | null
required
deprecated
hero
HeroConfig · object | null
required
deprecated

Hero section configuration for a page.

theme
ThemeConfig · object
required
deprecated

Theme configuration for public retriever UI.

Defines colors, fonts, and visual styling for the public search interface.

seo
SEOConfig · object | null
required
deprecated

SEO configuration for public retriever discoverability.

Auto-generated during publishing with sensible defaults inferred from the retriever's display_config. All fields can be overridden manually.

This configuration controls how the public retriever appears in:

  • Search engine results (Google, Bing, etc.)
  • Social media shares (Twitter, Facebook, LinkedIn)
  • Link previews in messaging apps
Example:
stats
StatItem · object[]
required
deprecated

Configuration for the featured gallery section.

tabs
PageTab · object[]
required
deprecated
password_protected
boolean
required
deprecated
has_unpublished_changes
boolean
default:false
monitoring_config
MonitoringConfig · object | null

Opt-in monitoring configuration for a Canvas app.

All monitoring is off by default except error_boundary_enabled, which is a client-side UX safety net (shows fallback UI instead of blank page) and sends no data externally.

When sentry_enabled or posthog_enabled are turned on, monitoring data is sent to Mixpeek-internal Sentry/PostHog — never to the customer's own observability stack. PII is stripped via beforeSend / mask_all_text, and session replay is always off.

repo_url
string | null
repo_branch
string | null
github_installation_id
integer | null
versions
VersionRecord · object[]

Deploy version history with timestamps and environment info