---
title: "List Apps"
method: GET
path: "/v1/apps"
tags: ["Apps"]
---

# List Apps

`GET /v1/apps`

List all Apps for this organization.

The response includes ``max_apps`` (the tier's Canvas App limit, ``null`` =
unlimited) so the UI can render usage ("X of N apps used") and gate the
create action without a second round-trip.

## Query parameters

- `limit` integer
- `offset` integer
- `template` string, nullable — Filter by template type
- `slug` string, nullable — Exact match on app slug
- `search` string, nullable — Case-insensitive partial match on app name

## Response `200`

Paginated list of Apps for this organization

- ListAppsResponse — Paginated list of apps.
  - `results` AppListItem[], required
    - `app_id` string, required
    - `slug` string, required
    - `url` string, required
    - `meta` PageMeta, 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.).
      - `title` string, required — Page title displayed in the browser tab and page header.
      - `description` string, nullable — Short page description shown in the page header or subtitle area.
      - `logo_url` string, nullable — URL of the logo displayed in the page header.
      - `favicon_url` string, nullable — URL of the favicon for the browser tab.
      - `indexable` boolean, nullable — When true, opts the app in to search-engine and AI crawler indexing. Canvas serves an Allow robots.txt and omits X-Robots-Tag/noindex. Defaults to false (noindex) for all apps.
    - `is_active` boolean, required
    - `version` integer, required
    - `has_unpublished_changes` boolean
    - `template` string, required
    - `custom_domains` CustomDomainConfig[], required
      - `domain` string, required — Customer domain (e.g. 'search.acme.com')
      - `status` 'pending' | 'verifying' | 'provisioning_tls' | 'active' — Domain verification and TLS lifecycle state
      - `verification_token` string, nullable — TXT record value for DNS ownership verification
      - `cname_target` string, nullable — CNAME target (e.g. '{slug}.mxp.co')
      - `tls_cert_id` string, nullable — TLS certificate reference
      - `tls_expires_at` string, date-time, nullable — TLS cert expiry
      - `verified_at` string, date-time, nullable — When domain was verified
      - `is_primary` boolean — Whether this is the primary domain
    - `auth_config` AuthConfigOutput — 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.
      - `mode` 'public' | 'clerk' | 'password' | 'api_key' | 'jwt' | 'sso_oidc' | 'sso_saml' — Authentication mode
      - `clerk_org_id` string, nullable — Clerk Organization ID for this app (auto-provisioned)
      - `clerk_allowed_providers` string[] — Enabled auth providers: google, github, email
      - `password_hash` string, nullable — Bcrypt hash of the password (internal — never exposed in API responses)
      - `saml_idp_metadata_url` string, nullable
      - `saml_sp_entity_id` string, nullable
      - `saml_acs_url` string, nullable
      - `oidc_issuer` string, nullable
      - `oidc_client_id` string, nullable
      - `oidc_client_secret_name` string, nullable — Secrets vault key name (never stored inline)
      - `oidc_scopes` string[]
      - `jwt_jwks_url` string, nullable
      - `jwt_audience` string, nullable
      - `jwt_issuer` string, nullable
      - `api_keys` object[]
    - `build_config` BuildConfig — JSX build configuration for an App. Phase 1: schema only. Phase 3: used by the build pipeline Celery task.
      - `entry` string — Build entry point
      - `framework` 'react'
      - `tailwind` boolean
      - `env_vars` object — Build-time environment variables injected into the app. Set MIXPEEK_API_KEY here to enable the /_api server-side proxy — without it the proxy falls back to the canvas server's default key. NOTE: every key here EXCEPT MIXPEEK_API_KEY is injected into the browser's window.__MIXPEEK__. For third-party secrets that must stay server-side (e.g. SERPAPI_KEY for a /functions/* handler), use ``secrets`` below, not ``env_vars``.
      - `secrets` object — Server-only secrets for the app's /functions/* server-side handlers, exposed to them as ``ctx.env``. NEVER injected into the browser window.__MIXPEEK__ and masked ('***') in API responses. Use for third-party API keys (e.g. SERPAPI_KEY).
      - `asset_prefix` string, nullable — CDN asset prefix once deployed
    - `monitoring_config` MonitoringConfig — 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.
      - `enabled` boolean — Master switch — must be true for any monitoring to activate
      - `error_boundary_enabled` boolean — Wrap app in a React Error Boundary that shows a fallback UI on crash. Client-side only — no data is sent externally. Enabled by default.
      - `sentry_enabled` boolean — Capture unhandled exceptions to Mixpeek-internal Sentry. No PII is captured (beforeSend strips it).
      - `posthog_enabled` boolean — Capture pageviews and error counts to Mixpeek-internal PostHog. No text content, no session recordings.
      - `custom_error_message` string, nullable — Custom message shown in the Error Boundary fallback UI
      - `auto_fix_enabled` boolean — When true, error spikes trigger the Claude-powered auto-fix pipeline. Requires source_files on the latest version or a connected GitHub repo.
    - `repo_url` string, nullable
    - `repo_branch` string, nullable
    - `environments` object
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
  - `total_count` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `max_apps` integer, nullable — Maximum Canvas Apps allowed on the caller's tier (Free=1, Pro=10, Enterprise=unlimited). null means unlimited.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/23e05292e326/schema)