App Configurations & Builds

An app configuration describes how your product is packaged for a single platform: web, iOS, Android, or desktop. It carries the per-platform identity (app name, bundle identifier, version), the launch presentation (icon, splash screen), and a free-form block of platform options. Once a platform is configured, the build pipeline turns it into a distributable app bundle, and the public build-config endpoint hands the right settings to each running client.

Pro App configurations and the build pipeline are part of Backbuild Pro. See pricing.

How the Pieces Fit Together

App configurations sit under a SaaS package. You create one app config per platform you want to ship, then reference that config when you kick off a build. The flow is:

1. Configure a platform: create an app config for each target (web, iOS, Android, Windows, macOS, Linux).
2. Build: create a build job that points at the app config and a build system; track it to completion.
3. Distribute: running clients fetch their settings from the public build-config endpoint, and native builds flow on to store submission and desktop release distribution.

App configs and builds are available through two equivalent route groups: the package-scoped paths under /v1/saas-packages/:packageId/app-configs, and the app-pipeline paths under /v1/app (which also host build jobs and screen definitions). Use whichever fits how you are working; both go through the same underlying configuration.

App Configuration Fields

Each app config is a per-platform record. The platform is fixed at creation; everything else can be refined as you iterate.

Signing material is never placed directly in the app config; only a reference to a stored signing configuration is. This keeps certificates and keys out of the configuration payload.

Creating an App Config

POST /v1/saas-packages/:packageId/app-configs

{
  "platform": "ios",
  "app_name": "My SaaS",
  "bundle_identifier": "com.mycompany.mysaas",
  "version_name": "1.0.0",
  "version_code": 1,
  "icon_url": "https://cdn.example.com/icon.png",
  "splash_screen_url": "https://cdn.example.com/splash.png",
  "splash_background_color": "#0A0A0A",
  "platform_config": {
    "theme": { "mode": "dark" },
    "navigation": { "style": "tabs" }
  }
}

Create one config per platform you intend to ship. Updates take only the fields you want to change, and optional URL or reference fields can be cleared by sending them as null on the package-scoped update path.

App Bundles & Builds

A build job turns an app config into a distributable bundle. You create a build by referencing the package, the app config, the platform, and the build system to run it on, then track the job’s status as it progresses.

A build job moves through pending → queued → in_progress and ends in success, failed, or cancelled. As it runs, the job records a build-log URL, the produced artifact URL, and any error message, so you can follow it from start to finish and retrieve the output.

# Start a production iOS build
POST /v1/app/builds

{
  "saas_package_id": ":packageId",
  "app_config_id": ":configId",
  "platform": "ios",
  "build_system": "eas_build",
  "build_type": "production"
}

You can list builds (filtered by package, platform, status, or build system), fetch a single build, update its status, and cancel a build that is still in flight.

Data Bundles

Alongside native builds, a data bundle is a versioned snapshot of the configuration and seed data a fresh tenant starts with. You create a bundle, then publish it to make it the current bundle, or roll back to a previous one. This lets running apps pick up configuration changes without a full rebuild. See Data Bundles for the full treatment; the endpoints live under /v1/app/bundles and /v1/saas-packages/:packageId/data-bundles.

Serving Configuration to Running Apps

Once a platform is configured, running clients need their settings at launch. Two public, cached endpoints handle that. No authentication is required, so they are fast to bootstrap from:

# Platform-specific build config for a domain (public, cached)
GET /v1/marketplace/build-config?domain=app.yourproduct.com&platform=ios

# Active build targets
GET /v1/marketplace/build-targets?domain=app.yourproduct.com

These responses are cached and safe to call on every page load or app launch. Updating your package’s presentation refreshes the cached configuration for any domains pointing at it.

Store Submission & Desktop Distribution

For native apps, the build output continues into the publishing pipeline:

• Store accounts and listings: connect your Apple, Google Play, or Microsoft store account, attach listing metadata (title, descriptions, screenshots, categories), set age ratings, run pre-submission compliance checks, and track submission status. These live under /v1/store.
• Desktop releases: publish versioned desktop releases and channels, with signing-key management and a public current-release lookup, under /v1/releases.

Those surfaces are covered in their own pages; this page focuses on configuring the app per platform and producing the build.

API Reference

App-config and build endpoints require an authenticated session in your organization. The build-config, app-config, and build-targets discovery endpoints under /v1/marketplace are public and cached.

Create App Config

POST /v1/saas-packages/:packageId/app-configs

Request Body

Responds 201 with the created app config. A dangling :packageId returns 404; an invalid body returns 400.

List App Configs

GET /v1/saas-packages/:packageId/app-configs

Query Parameters

Returns a paginated list of app configs.

Get App Config

GET /v1/saas-packages/:packageId/app-configs/:configId

Returns the full app-config record, or 404 if not found in your organization.

Update App Config

PUT /v1/saas-packages/:packageId/app-configs/:configId

Request Body

At least one field is required. Responds 200 with the updated record.

Delete App Config

DELETE /v1/saas-packages/:packageId/app-configs/:configId

Removes the app config. Responds 404 if it does not exist.

App-Pipeline Paths (Equivalent)

The same app configs are reachable directly by ID under the app-pipeline router, which also hosts build jobs. On these paths the package is supplied as a body field on create and a saas_package_id query parameter on list.

POST   /v1/app/configs
GET    /v1/app/configs?saas_package_id=:packageId&platform=ios
GET    /v1/app/configs/:configId
PUT    /v1/app/configs/:configId
DELETE /v1/app/configs/:configId

Build Jobs

POST   /v1/app/builds
GET    /v1/app/builds?saas_package_id=:packageId&status=in_progress
GET    /v1/app/builds/:buildId
PUT    /v1/app/builds/:buildId/status
POST   /v1/app/builds/:buildId/cancel

Create Build: Request Body

The build-status query and update accept pending, queued, in_progress, success, failed, and cancelled. A status update can also record a build_log_url, artifact_url, and error_message.

Public Configuration & Discovery

GET /v1/marketplace/app-config?domain=app.yourproduct.com
GET /v1/marketplace/build-config?domain=app.yourproduct.com&platform=ios
GET /v1/marketplace/build-targets?domain=app.yourproduct.com

Pair this with Screen Definitions to shape what each platform renders, or return to the SaaS Builder overview.

Frequently Asked Questions

Do I configure each platform separately?

Yes. App configuration is per platform (web, iOS, Android, and desktop), so each target can carry its own settings and native assets.

How does a running app get its configuration?

It fetches its configuration keyed by the domain it is served from, at startup, so it renders correctly from the first paint without a rebuild.

Where do native app icons and splash screens live?

On the per-platform app configuration. See Branding & Themes for the brand assets involved.