Skip to content

Mini App URLs

Mini Apps have a canonical URL that can be used to share across social feeds and web sites. The URL format is as follows:

https://farcaster.xyz/miniapps/<app-id>/<app-slug>(/<sub-path>)(?<query-params>)

  • The <app-id> is a unique identifier assigned to the Mini App when it is published.
  • The <app-slug> is a kebab-case version of the Mini App name, used to create a more readable URL.
  • The <sub-path> is an optional path appended to the Mini App’s homeURL when it is opened.
  • The <query-params> are optional parameters added to the homeURL as a query string when the Mini App is opened.

The <sub-path> and <query-params> are optional and can be used to navigate to a specific page in the Mini App or pass data to the Mini App.

When a user clicks a Mini App URL and is logged in:

  • On web: the Mini App opens in the mini app drawer.
  • On mobile: the browser deep links to the Farcaster app and opens the Mini App.

Where to find the Mini App URL

On the web Developers page, click the top-right kebab menu on one of your Mini App cards and select "Copy link to mini app". This copies the Mini App URL to your clipboard.

When the Mini App is open, tap on the top-right kebab menu and select "Copy link" to copy the Mini App URL to your clipboard.

Copy link to mini app

Copy link to mini app on the Developers page or the Mini App screen.

How to control what is displayed when I share a Mini App URL

Farcaster automatically generates OpenGraph meta tags for Mini App URLs, ensuring they render correctly when shared on social platforms or web apps that support embedded link previews, such as X.

To make sure your Mini App displays as intended, include the fc:frame meta tag on all Mini App URLs (see "Sharing your app") and add all relevant fields in your application config, especially ogTitle, ogDescription and ogImageUrl.

How Mini App sub-paths and query params work

Each Mini App defines a homeUrl property in its application config. When a user clicks on a Mini App in the Farcaster client's Mini App explorer, a WebView (on mobile) or iframe (on web) pointing to the homeUrl is opened.

If you share a Mini App URL with a sub-path and/or query parameters, those are appended to the homeUrl's path and query string.

For example, if the homeUrl is https://example.com/miniapp/v1 and the Mini App URL is https://farcaster.xyz/miniapps/12345/example-miniapp/leaderboard?sort=points, the WebView or iframe will load https://example.com/miniapp/v1/leaderboard?sort=points.

FAQ

Is there another way to get a Mini App's id?

Not at the moment.

When copying the link from the Mini App header, it doesn't copy the Mini App URL, why is that?

Any URL with a valid fc:frame meta tag shared in a cast will be treated as a Mini App. Copying the link from these Mini Apps will copy the original URL shared in the cast, not the canonical Mini App URL.

Can I add a sub-path or query params to the Mini App URL copied from the Mini App header?

Not at the moment. Only the canonical Mini App URL or URL shared in the cast will be copied.

Can I open a Mini App from another Mini App?

Yes, you can open a Mini App from another Mini App by using the openUrl action. However, this prompts to close the current app when the new app is opened and there is no way to navigate back.

import { sdk } from '@farcaster/frame-sdk'
 
const url = 'https://farcaster.xyz/miniapps/deoWzfI9kLjH/rewards'
await sdk.actions.openUrl(url)