Skip to main content
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
ConstraintValue
ProtocolHTTPS required (HTTP allowed for localhost in development only)
Timeout10 seconds
Maximum size10 KB
Maximum redirects3
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",
    "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

​
Validated automatically

The manifest parser rejects any manifest missing these three fields:
FieldTypeConstraints
frame.namestringDisplay name. Recommended ≤32 chars.
frame.iconUrlstringApp icon. See Media specs.
frame.homeUrlstringHTTPS launch URL. Recommended ≤1024 chars.

​
Required for submission review

The following fields are not parser-enforced but are required for your Mini App to pass review, appear correctly in the explorer, and qualify for featured placement. A manifest missing any of these will be rejected during manual review.
FieldTypeNotes
frame.versionstringMust be "1"
frame.primaryCategorystringOne value from Categories.
frame.heroImageUrlstringImage shown on the app grid card.
startale.featuredBannerImageUrlstringFeatured rotation banner at the top of the explorer.
startale.screenCompatibility.desktopbooleantrue = full browser on desktop; false = default 424×695 px portrait frame. Omitting it shows a Missing flag in the validator.

​
Optional fields

FieldTypeNotes
frame.taglinestringOne-line pitch shown on the app card. Max 30 chars.
frame.splashImageUrlstringCentered icon on the loading screen. 200×200px, PNG/JPG/WebP, max 50KB.
frame.splashBackgroundColorstringHex color for the splash background.
frame.tagsstring[]Up to 5 tags, lowercase alphanumeric + hyphens, ≤20 chars each. Used for explorer search and filtering.
frame.webhookUrlstringNotification endpoint. Required for push notifications.
startale.manifestVersionstringStartale manifest spec version. Use "2.3" for new manifests.
startale.projectWebsitestringHTTPS URL to your main project site.
startale.socialLinksobjectObject with twitter, discord, telegram, farcaster, website keys.
startale.screenCompatibility.landscapeOnlybooleanWhen true, content rotates 90° when the viewport is portrait. Default false.

​
URL rules

Every URL in the manifest is validated. Failures reject the manifest.
RuleDetail
ProtocolHTTPS required. HTTP only for localhost and 127.0.0.1 in development.
Private IPv4 ranges blocked0.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 blockedLoopback (::1), link-local (fe80::/10), unique local (fc00::/7)
Localhost in productionBlocked
The same rules apply to every image URL in the manifest. When the Startale App displays your banner, it tries fields in this priority order:
  1. startale.featuredBannerImageUrl
  2. frame.imageUrl
  3. frame.heroImageUrl
  4. frame.splashImageUrl
  5. 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.