API Documentation

Build native apps and check build status programmatically with your API key. Uses your paid credits — also called API credits.

Build endpoint Get your API key

JSON responses API-key auth 3 endpoints

quick start

# 1 — Build an app
curl -X POST https://freeappmaker.pro/api/build \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"appName":"My App",
       "websiteUrl":"https://example.com",
       "packageName":"com.example.app",
       "target":"apk"}'

# → { "buildId": "3f2a...", "status": "queued" }

Auth Costs Build Nav Money Status Credits Limits Codes

Authentication

Every request must include your API key, found in Settings → API Key Send it in either header:

headers

Authorization: Bearer <your-api-key>
# or
x-api-key: <your-api-key>

Keep this key secret — anyone with it can build apps and spend your credits.

Build costs

Each build spends your purchased (paid) credits — API builds do not use the daily free credits.

Android APK

credits · target="apk"

Android AAB

credits · target="aab"

iOS build

credits · target="ipa"

POST/api/build

Build a native app from a website. Returns a buildId you can poll with the status endpoint.

Body parameters (application/json)

appNameRequired

string

Display name (2–50 chars).

websiteUrlRequired

string (url)

The website to wrap.

packageNameRequired

string

Reverse-domain id, e.g. com.company.app.

targetRequired

"apk" | "aab" | "ipa"

Build format.

primaryColorOptional

string (#RRGGBB)

Brand color. Default #F97316.

accentColorOptional

string (#RRGGBB)

Accent color. Default #0EA5E9.

statusBarColorOptional

string (#RRGGBB)

Status bar color. Default = primaryColor.

themeOptional

"light" | "dark" | "system"

Default system.

navigationOptional

"bottom" | "drawer" | "tabs" | "none"

Native nav style. Default none (plain full-screen WebView).

navItemsOptional

NavItem[]

Up to 6 navigation entries for bottom/tabs/drawer. Ignored when navigation is "none". See the Navigation items section below for the object shape and valid icons.

featuresOptional

string[]

Feature flags: push, offline, pullToRefresh, camera, location, darkMode, exitConfirmation. Add "admob" to run your own ads and "noAds" to disable all ads (see Monetization).

iconUrlOptional

string (url)

1024×1024 app icon. A branded icon is generated if omitted.

splashUrlOptional

string (url)

Splash image (shown full-screen).

splashStyleOptional

string

"gradient" | "solid" | "centered" | "minimal" | "dark".

orientationOptional

"portrait" | "landscape" | "auto"

Screen lock. Default portrait.

appVersionOptional

string

Version name, e.g. "1.0.0". Build number auto-increments.

rateAppEnabledOptional

boolean

Prompt users to rate after N launches.

rateAppAfterSessionsOptional

number (1–100)

Launches before the rate prompt.

urlWhitelistOptional

string

Newline-separated domains that stay in-app.

urlBlacklistOptional

string

Newline-separated domains opened in the system browser.

startAppAppIdOptional

string

Your own Start.io (StartApp) App ID for the free tier. Empty = our default sponsored ads.

admobAppIdOptional

string

Your AdMob App ID, e.g. ca-app-pub-…~…. Requires "admob" feature + a plan that allows own ads.

admobBannerIdOptional

string

AdMob banner ad unit id, e.g. ca-app-pub-…/….

admobInterstitialIdOptional

string

AdMob interstitial ad unit id, e.g. ca-app-pub-…/….

admobPlacementOptional

"banner" | "interstitial" | "both"

Where AdMob ads appear. Default banner.

oneSignalAppIdOptional

string (uuid)

OneSignal App ID for push notifications. Requires the "push" feature + a plan that allows own integrations.

appIdOptional

string (uuid)

Rebuild/update an existing app you own.

Parameter	Type	Required	Description
appName	string	Required	Display name (2–50 chars).
websiteUrl	string (url)	Required	The website to wrap.
packageName	string	Required	Reverse-domain id, e.g. com.company.app.
target	"apk" \| "aab" \| "ipa"	Required	Build format.
primaryColor	string (#RRGGBB)	Optional	Brand color. Default #F97316.
accentColor	string (#RRGGBB)	Optional	Accent color. Default #0EA5E9.
statusBarColor	string (#RRGGBB)	Optional	Status bar color. Default = primaryColor.
theme	"light" \| "dark" \| "system"	Optional	Default system.
navigation	"bottom" \| "drawer" \| "tabs" \| "none"	Optional	Native nav style. Default none (plain full-screen WebView).
navItems	NavItem[]	Optional	Up to 6 navigation entries for bottom/tabs/drawer. Ignored when navigation is "none". See the Navigation items section below for the object shape and valid icons.
features	string[]	Optional	Feature flags: push, offline, pullToRefresh, camera, location, darkMode, exitConfirmation. Add "admob" to run your own ads and "noAds" to disable all ads (see Monetization).
iconUrl	string (url)	Optional	1024×1024 app icon. A branded icon is generated if omitted.
splashUrl	string (url)	Optional	Splash image (shown full-screen).
splashStyle	string	Optional	"gradient" \| "solid" \| "centered" \| "minimal" \| "dark".
orientation	"portrait" \| "landscape" \| "auto"	Optional	Screen lock. Default portrait.
appVersion	string	Optional	Version name, e.g. "1.0.0". Build number auto-increments.
rateAppEnabled	boolean	Optional	Prompt users to rate after N launches.
rateAppAfterSessions	number (1–100)	Optional	Launches before the rate prompt.
urlWhitelist	string	Optional	Newline-separated domains that stay in-app.
urlBlacklist	string	Optional	Newline-separated domains opened in the system browser.
startAppAppId	string	Optional	Your own Start.io (StartApp) App ID for the free tier. Empty = our default sponsored ads.
admobAppId	string	Optional	Your AdMob App ID, e.g. ca-app-pub-…~…. Requires "admob" feature + a plan that allows own ads.
admobBannerId	string	Optional	AdMob banner ad unit id, e.g. ca-app-pub-…/….
admobInterstitialId	string	Optional	AdMob interstitial ad unit id, e.g. ca-app-pub-…/….
admobPlacement	"banner" \| "interstitial" \| "both"	Optional	Where AdMob ads appear. Default banner.
oneSignalAppId	string (uuid)	Optional	OneSignal App ID for push notifications. Requires the "push" feature + a plan that allows own integrations.
appId	string (uuid)	Optional	Rebuild/update an existing app you own.

Example

curl

curl -X POST https://freeappmaker.pro/api/build \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "My App",
    "websiteUrl": "https://example.com",
    "packageName": "com.example.app",
    "target": "apk",
    "primaryColor": "#F97316",
    "features": ["pullToRefresh", "offline"]
  }'

Response 200

json

{
  "success": true,
  "buildId": "3f2a...-uuid",
  "appId": "9b1c...-uuid",
  "target": "apk",
  "cost": 5,
  "status": "queued",
  "statusUrl": "/api/build/status?buildId=3f2a...-uuid"
}

Navigation items

When navigation is bottom, tabs or drawer, the app renders a native menu built from navItems. Send up to 6 items — each is a JSON object. The array is ignored when navigation is none. If you omit it while using a nav style, a sensible default (Home / Search / Account) is applied.

NavItem object

idRequired

string (≤40)

Stable unique key for the item, e.g. home.

labelRequired

string (≤40)

Text shown under/next to the icon, e.g. Home.

iconRequired

string (≤40)

One of the icon names below. Unknown names fall back to a generic dot.

pathRequired

string (≤400)

Where the item goes. A path like "/cart" is resolved against your websiteUrl; a full https URL is also allowed.

openModeOptional

"internal" | "external"

internal (default) opens inside the app WebView; external opens in the system browser.

Parameter	Type	Required	Description
id	string (≤40)	Required	Stable unique key for the item, e.g. home.
label	string (≤40)	Required	Text shown under/next to the icon, e.g. Home.
icon	string (≤40)	Required	One of the icon names below. Unknown names fall back to a generic dot.
path	string (≤400)	Required	Where the item goes. A path like "/cart" is resolved against your websiteUrl; a full https URL is also allowed.
openMode	"internal" \| "external"	Optional	internal (default) opens inside the app WebView; external opens in the system browser.

Icon names

Pass the icon value as one of these strings:

homesearchcartaccountheartbellmenuinfogridtagsettingsmailphonechatbookmarkstarcalendarimagemusicvideomapgiftzapcoffeecompasspackagetruckwalletnewspaperfilefolderuserstrophygamepadplaybagcarddollarpercentclocksendsharedownloadglobebriefcasebookheadphonesfilmtvfoodlikeflamelistdashboardcharttrendingawardtickethelp

Example

json

"navigation": "bottom",
"navItems": [
  { "id": "home",   "label": "Home",   "icon": "home",   "path": "/" },
  { "id": "shop",   "label": "Shop",   "icon": "cart",   "path": "/shop" },
  { "id": "account","label": "Account","icon": "account","path": "/my-account" },
  { "id": "help",   "label": "Support","icon": "help",
    "path": "https://help.example.com", "openMode": "external" }
]

Monetization

Every build can show ads. How ads are served depends on the app plan and its features:

Free tier (default) — sponsored Start.io ads are shown and earnings are credited to the platform. Provide startAppAppId to earn into your own Start.io account instead.
Own ads (AdMob) — once the app is on a plan that allows own ads (Revenue Pro or higher), add "admob" to features and send your AdMob ids to run your own ad units. The plan is a paid, per-app upgrade managed on the Billing page — it is not set from the build request, and AdMob ids are ignored until the app is upgraded.
No ads — add "noAds" to features to build the app with no ads at all.

Monetization parameters

features: ["admob"]Optional

flag

Enable your own AdMob ad units (requires the app to be upgraded to an own-ads plan via Billing).

features: ["noAds"]Optional

flag

Disable all ads in the built app.

startAppAppIdOptional

string

Your Start.io App ID (free tier). Empty = platform default ads.

admobAppIdOptional

string

AdMob App ID, e.g. ca-app-pub-0000000000000000~1111111111.

admobBannerIdOptional

string

AdMob banner unit, e.g. ca-app-pub-0000000000000000/2222222222.

admobInterstitialIdOptional

string

AdMob interstitial unit, e.g. ca-app-pub-0000000000000000/3333333333.

admobPlacementOptional

"banner" | "interstitial" | "both"

Where AdMob ads show. Default banner.

oneSignalAppIdOptional

string (uuid)

OneSignal App ID for push (requires "push" feature + an own-integrations plan).

Parameter	Type	Required	Description
features: ["admob"]	flag	Optional	Enable your own AdMob ad units (requires the app to be upgraded to an own-ads plan via Billing).
features: ["noAds"]	flag	Optional	Disable all ads in the built app.
startAppAppId	string	Optional	Your Start.io App ID (free tier). Empty = platform default ads.
admobAppId	string	Optional	AdMob App ID, e.g. ca-app-pub-0000000000000000~1111111111.
admobBannerId	string	Optional	AdMob banner unit, e.g. ca-app-pub-0000000000000000/2222222222.
admobInterstitialId	string	Optional	AdMob interstitial unit, e.g. ca-app-pub-0000000000000000/3333333333.
admobPlacement	"banner" \| "interstitial" \| "both"	Optional	Where AdMob ads show. Default banner.
oneSignalAppId	string (uuid)	Optional	OneSignal App ID for push (requires "push" feature + an own-integrations plan).

Example — own AdMob (app already on a paid plan)

json

{
  "appName": "My Shop",
  "websiteUrl": "https://shop.example.com",
  "packageName": "com.example.shop",
  "target": "aab",
  "features": ["admob", "pullToRefresh"],
  "admobAppId": "ca-app-pub-0000000000000000~1111111111",
  "admobBannerId": "ca-app-pub-0000000000000000/2222222222",
  "admobInterstitialId": "ca-app-pub-0000000000000000/3333333333",
  "admobPlacement": "both"
}

Games wrapped from Gamezop always use the game provider's own ads, so Start.io and AdMob fields are ignored for them.

GET/api/build/status

Check the status of a build you started. Poll every few seconds until status is completed or failed.

Query parameters

buildIdRequired

string (uuid)

The id returned by POST /api/build.

Parameter	Type	Required	Description
buildId	string (uuid)	Required	The id returned by POST /api/build.

Example

curl

curl "https://freeappmaker.pro/api/build/status?buildId=<buildId>" \
  -H "Authorization: Bearer <your-api-key>"

Response 200

json

{
  "success": true,
  "buildId": "3f2a...-uuid",
  "status": "completed",
  "progress": 100,
  "target": "apk",
  "error": null,
  "artifacts": [
    { "name": "app-release.apk", "size": "12 MB",
      "url": "/api/public/artifact/<token>/app-release.apk" }
  ]
}

status is one of: queued, running, completed, failed, canceled. Download links appear once the build completes.

GET/api/credits/balance

Check your current credit balance before starting a build. Read-only — nothing is charged. Your daily free allowance is applied automatically.

Example

curl

curl "https://freeappmaker.pro/api/credits/balance" \
  -H "Authorization: Bearer <your-api-key>"

Response 200

json

{
  "success": true,
  "balance": {
    "free": 8,       // free credits left today
    "freeMax": 10,   // daily free allowance
    "paid": 500,     // purchased credits remaining
    "total": 508     // free + paid
  }
}

A build is rejected with 402 Payment Required when total is less than the build cost.

Rate limits

Limits are applied per API key on a 60-second rolling window. Exceeding a limit returns 429 Too Many Requests with a Retry-After header (seconds to wait).

POST /api/buildOptional

3 / minute

Start a new build.

GET /api/build/statusOptional

30 / minute

Poll build status.

GET /api/credits/balanceOptional

30 / minute

Check credit balance.

Parameter	Type	Required	Description
POST /api/build	3 / minute	Optional	Start a new build.
GET /api/build/status	30 / minute	Optional	Poll build status.
GET /api/credits/balance	30 / minute	Optional	Check credit balance.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining. When polling build status, wait a few seconds between requests to stay within the limit.

Response codes

200Optional

Request succeeded.

400Optional

Bad Request

Invalid JSON or parameters (see 'details').

401Optional

Unauthorized

Missing or invalid API key.

402Optional

Payment Required

Not enough credits (includes current balance).

404Optional

Not Found

Build not found for your account.

429Optional

Too Many Requests

Rate limit exceeded — see 'Retry-After' header.

500Optional

Server Error

Unexpected failure.

Parameter	Type	Required	Description
200	OK	Optional	Request succeeded.
400	Bad Request	Optional	Invalid JSON or parameters (see 'details').
401	Unauthorized	Optional	Missing or invalid API key.
402	Payment Required	Optional	Not enough credits (includes current balance).
404	Not Found	Optional	Build not found for your account.
429	Too Many Requests	Optional	Rate limit exceeded — see 'Retry-After' header.
500	Server Error	Optional	Unexpected failure.

Ready to build with the API?

Grab your API key from Settings and ship your first build in minutes.

Get API key View credit packs