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" }
AuthCostsBuildStatusCreditsLimitsCodes

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

5

Android AAB

10

iOS build

20

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

Array<{ id, label, icon, path, openMode? }>

Up to 6 nav items for bottom/tabs/drawer. openMode: "internal" (default) or "external". Ignored when navigation is "none".

featuresOptional

string[]

e.g. push, offline, pullToRefresh, camera, location, darkMode, exitConfirmation.

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.

appIdOptional

string (uuid)

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"
}
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.

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.

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

OK

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.

Ready to build with the API?

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

Get API keyView credit packs