API Reference

All endpoints are served from the Experience Service at https://experience.shellapps.com.

Authentication

All API endpoints require authentication:

Ingest endpoints (/api/v1/events/ingest, /api/v1/errors/ingest): App API key via X-API-Key header
Dashboard/management endpoints: Bearer token via Authorization header (validated against auth.shellapps.com)
SDK resolve endpoints (/api/v1/flags/resolve, /api/v1/translations): App API key OR Bearer token

App Registration

Method	Path	Auth	Description
`POST`	`/api/v1/apps/register`	Bearer	Register app, get API key
`GET`	`/api/v1/apps`	Bearer	List registered apps
`GET`	`/api/v1/apps/:id`	Bearer	App detail
`POST`	`/api/v1/apps/:id/rotate-key`	Bearer	Rotate API key

Register an App

curl -X POST https://experience.shellapps.com/api/v1/apps/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'
 
# Response: { "appId": "abc123", "apiKey": "exp_xxxxxxxxxxxx" }

Events

Method	Path	Auth	Description
`POST`	`/api/v1/events/ingest`	API Key	Ingest protobuf EventBatch
`POST`	`/api/v1/events/ingest/json`	API Key	Ingest JSON events (debug)
`GET`	`/api/v1/events/query`	Bearer	Query events with filters
`GET`	`/api/v1/events/aggregate`	Bearer	Aggregated analytics
`GET`	`/api/v1/events/sessions/:sessionId`	Bearer	Full session event stream
`GET`	`/api/v1/events/heatmap`	Bearer	Heatmap data for a page

See Event Tracking for details on the tracking system and Data Models for protobuf schemas.

Errors

Method	Path	Auth	Description
`POST`	`/api/v1/errors/ingest`	API Key	Ingest protobuf ErrorBatch
`POST`	`/api/v1/errors/ingest/json`	API Key	Ingest JSON errors (debug)
`GET`	`/api/v1/errors`	Bearer	List error groups
`GET`	`/api/v1/errors/:id`	Bearer	Error group detail
`PUT`	`/api/v1/errors/:id`	Bearer	Update status
`POST`	`/api/v1/errors/:id/comment`	Bearer	Add team comment
`GET`	`/api/v1/errors/stats`	Bearer	Error rate stats

See Error Monitoring for details on error capture, grouping, and the crash UI.

Feature Flags

Method	Path	Auth	Description
`POST`	`/api/v1/flags`	Bearer	Create flag
`GET`	`/api/v1/flags`	Bearer	List flags for app
`GET`	`/api/v1/flags/:id`	Bearer	Flag detail + rules
`PUT`	`/api/v1/flags/:id`	Bearer	Update flag
`DELETE`	`/api/v1/flags/:id`	Bearer	Delete flag
`POST`	`/api/v1/flags/:id/rules`	Bearer	Add rule
`PUT`	`/api/v1/flags/:id/rules/:ruleId`	Bearer	Update rule
`DELETE`	`/api/v1/flags/:id/rules/:ruleId`	Bearer	Delete rule
`GET`	`/api/v1/flags/:appId/resolve`	API Key/Bearer	Get resolved flags for profile
`GET`	`/api/v1/flags/:appId/resolve/stream`	API Key	SSE stream for real-time updates

See Feature Flags for rule evaluation, rollouts, and experiments.

Experiments

Method	Path	Auth	Description
`POST`	`/api/v1/experiments`	Bearer	Create experiment
`GET`	`/api/v1/experiments/:id`	Bearer	Experiment detail
`GET`	`/api/v1/experiments/:id/results`	Bearer	Experiment results + stats

Translations

Method	Path	Auth	Description
`POST`	`/api/v1/translations/webhook`	Webhook Secret	GitHub webhook receiver
`POST`	`/api/v1/translations/:appId/upload`	Bearer	Manual string upload
`GET`	`/api/v1/translations/:appId/:locale`	API Key/Bearer	Get translations for locale
`GET`	`/api/v1/translations/:appId/locales`	API Key/Bearer	List available locales
`PUT`	`/api/v1/translations/:appId/:locale/:key`	Bearer	Override a translation
`POST`	`/api/v1/translations/:appId/configure`	Bearer	Set target languages
`GET`	`/api/v1/translations/:appId/status`	Bearer	Translation progress
`GET`	`/api/v1/translations/:appId/recommend`	Bearer	Recommended languages

See Translations for the full translation management flow and GitHub integration.

Feedback

Method	Path	Auth	Description
`POST`	`/api/v1/feedback`	API Key/Bearer	Submit feedback
`GET`	`/api/v1/feedback`	Bearer	List feedback for app
`GET`	`/api/v1/feedback/:id`	Bearer	Feedback detail + thread
`POST`	`/api/v1/feedback/:id/reply`	Bearer	Reply to feedback
`PUT`	`/api/v1/feedback/:id/status`	Bearer	Update status
`PUT`	`/api/v1/feedback/:id/tags`	Bearer	Update tags
`POST`	`/api/v1/feedback/:id/upvote`	API Key/Bearer	Upvote feature request
`GET`	`/api/v1/feedback/stats`	Bearer	Feedback volume stats

See User Feedback for the feedback widget, dashboard, and thread system.

Themes

Method	Path	Auth	Description
`POST`	`/api/v1/themes`	Bearer	Create theme
`GET`	`/api/v1/themes`	Bearer	List user's themes
`GET`	`/api/v1/themes/store`	Bearer	Browse public theme store
`GET`	`/api/v1/themes/:id`	API Key/Bearer	Get theme definition
`PUT`	`/api/v1/themes/:id`	Bearer	Update theme
`POST`	`/api/v1/themes/:id/publish`	Bearer	Publish to store
`POST`	`/api/v1/themes/:id/install`	Bearer	Install theme
`POST`	`/api/v1/themes/:id/rate`	Bearer	Rate theme

See Theming for the theme builder and theme store.

App Analysis

Method	Path	Auth	Description
`POST`	`/api/v1/analysis/scan`	Bearer	Trigger automated scan
`GET`	`/api/v1/analysis/scans`	Bearer	List scans
`GET`	`/api/v1/analysis/scans/:id`	Bearer	Scan results
`POST`	`/api/v1/analysis/profile`	Bearer	Create manual app profile
`GET`	`/api/v1/analysis/profiles`	Bearer	List app profiles
`GET`	`/api/v1/analysis/compare`	Bearer	Compare apps
`POST`	`/api/v1/analysis/pricing-suggest`	Bearer	AI pricing recommendations

See App Analysis for automated and manual analysis modes.

React SDK Data Models