Manifest

Every Mini App publishes a manifest at a fixed path. The Startale App fetches this file to register, display, and launch your Mini App.

Location

GET https://<your-domain>/.well-known/farcaster.json

Constraint	Value
Protocol	HTTPS required (HTTP allowed for `localhost` in development only)
Timeout	10 seconds
Maximum size	10 KB
Maximum redirects	3

Private IP addresses and reserved ranges are blocked at fetch time. See URL rules.

Validate your manifest before submitting at app.startale.com/developers/manifest.

Top-level structure

Use the frame key. It is the Farcaster standard, so a single farcaster.json file works on Startale, Farcaster, and Base without rename. Startale-specific fields (featuredBannerImageUrl, projectWebsite, socialLinks, screenCompatibility) live under a root-level startale key, sibling to frame.

{
  "frame": {
    "version": "1",
    "name": "Your App Name",
    "tagline": "One-line pitch here",
    "description": "What your Mini App does and why a new user should open it",
    "iconUrl": "https://your-app.com/icon.webp",
    "homeUrl": "https://your-app.com",
    "splashImageUrl": "https://your-app.com/splash.png",
    "splashBackgroundColor": "#1a1a2e",
    "heroImageUrl": "https://your-app.com/hero.webp",
    "primaryCategory": "games",
    "tags": ["game", "web3", "soneium"],
    "webhookUrl": "https://your-app.com/api/notify"
  },
  "startale": {
    "manifestVersion": "2.3",
    "screenCompatibility": {
      "desktop": true,
      "landscapeOnly": false
    },
    "featuredBannerImageUrl": "https://your-app.com/banner.webp",
    "projectWebsite": "https://your-app.com",
    "socialLinks": {
      "twitter": "https://x.com/yourapp",
      "discord": "https://discord.gg/abc123",
      "telegram": "https://t.me/yourapp"
    }
  }
}

Required fields

The manifest parser rejects any manifest missing these three fields:

Field	Type	Constraints
`frame.name`	string	Display name. Recommended ≤32 chars.
`frame.iconUrl`	string	App icon. See Media specs.
`frame.homeUrl`	string	The URL your Mini App opens at. It can include a path or query string, for example for attribution. Recommended ≤1024 chars.

One homeUrl per app, even across language editions. Use the same homeUrl for the Global and Japan editions, and detect the edition at runtime with context.startale.language instead of a separate language URL. Notifications identify your Mini App by the origin of homeUrl (scheme + host), so a build served from a different origin is treated as a separate Mini App and does not share its subscriptions. See Notifications for how senderId is used.

Optional fields

The parser accepts a manifest without these fields, so your Mini App still loads. The manifest validator is stricter: it requires version, primaryCategory, heroImageUrl, tagline, and description. To be listed in the Startale App, some fields are required for review. See Submission.

Field	Type	Notes
`frame.version`	string	Must be `"1"`.
`frame.description`	string	What your Mini App does, shown in the app list and on your app page. Max 170 chars, no emoji. See Description fallback.
`frame.tagline`	string	Short one-line pitch, shown when `description` is not set. Max 30 chars.
`frame.primaryCategory`	string	One value from Categories.
`frame.heroImageUrl`	string	Image shown on the app grid card.
`frame.splashImageUrl`	string	Centered icon on the loading screen. 200×200px, PNG/JPG/WebP, max 50KB.
`frame.splashBackgroundColor`	string	Hex color for the splash background.
`frame.tags`	string[]	Up to 5 tags, lowercase alphanumeric + hyphens, ≤20 chars each. Used for explorer search and filtering.
`frame.webhookUrl`	string	Notification endpoint. Required for push notifications.
`startale.manifestVersion`	string	Startale manifest spec version. Use `"2.3"` for new manifests.
`startale.featuredBannerImageUrl`	string	Featured rotation banner at the top of the explorer.
`startale.screenCompatibility.desktop`	boolean	`true` = full browser on desktop; `false` = default 424×695 px portrait frame. Omitting it shows a Missing flag in the validator.
`startale.projectWebsite`	string	HTTPS URL to your main project site.
`startale.socialLinks`	object	Object with `twitter`, `discord`, `telegram`, `farcaster`, `website` keys.
`startale.screenCompatibility.landscapeOnly`	boolean	When `true`, content rotates 90° when the viewport is portrait. Default `false`.

URL rules

Every URL in the manifest is validated. Failures reject the manifest.

Rule	Detail
Protocol	HTTPS required. HTTP only for `localhost` and `127.0.0.1` in development.
Private IPv4 ranges blocked	`0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `198.18.0.0/15`, `240.0.0.0/4`
Private IPv6 ranges blocked	Loopback (`::1`), link-local (`fe80::/10`), unique local (`fc00::/7`)
Localhost in production	Blocked

The same rules apply to every image URL in the manifest.

Description fallback

The Startale App describes your Mini App with the first of these that is set:

frame.description
frame.tagline, unless it only repeats your category name
Nothing on your app page, and a generic “Tap to explore this Mini App.” placeholder in the app list

Set description. At 30 characters, a tagline is too short to tell a new user what your Mini App does. Your app page shows up to four lines of it. The app list shows it on desktop only, on one line, with the full text on hover. The manifest validator flags a missing or blank tagline or description, and one over 30 or 170 characters. An over-length value is still displayed. Do not use emoji in description. The Farcaster specification, which the manifest follows, does not allow emoji or special characters in this field. The character count also counts each emoji as 2 or more characters. When the Startale App displays your banner, it tries fields in this priority order:

startale.featuredBannerImageUrl
frame.imageUrl
frame.heroImageUrl
frame.splashImageUrl
frame.iconUrl

Provide featuredBannerImageUrl (2400×1260 px) for the best result.

Reusing a Farcaster or Base manifest

If your Mini App is already live on Farcaster or Base, your existing farcaster.json works on Startale unchanged. Add a root-level startale key (sibling to frame) with the Startale-specific fields (featuredBannerImageUrl, projectWebsite, socialLinks, screenCompatibility). A single file works on all three platforms.

Overview

Host APIs

Platform capabilities

Notifications

Ship it

Manifest

Location

Top-level structure

Required fields

Optional fields

URL rules

Description fallback

Banner fallback chain

Reusing a Farcaster or Base manifest

​Location

​Top-level structure

​Required fields

​Optional fields

​URL rules

​Description fallback

​Banner fallback chain

​Reusing a Farcaster or Base manifest

Location

Top-level structure

Required fields

Optional fields

URL rules

Description fallback

Banner fallback chain

Reusing a Farcaster or Base manifest