Skip to main content
The Builds API lets you trigger and monitor Capwrapper build jobs programmatically. Submit your web app URL and configuration to start a build, then poll the status endpoint until the build completes and a download URL is available. All endpoints require a valid API key — see the REST API overview for authentication details.

​
Create a build

POST /api/v1/builds Triggers a new build for your web app. Returns a build object with an id you can use to poll for status.

​
Request body

​
url
string
required
The public HTTPS URL of your web app. Must be publicly accessible at build time.
​
appName
string
required
Display name for your app. This is the name shown on the device home screen and in the app store listing.
​
bundleId
string
required
Unique app identifier in reverse domain notation (e.g. com.example.myapp). Must be unique across all your builds for a given platform.
​
version
string
required
Semver version string (e.g. "1.2.0"). Must be higher than the version used in the previous build for the same bundle ID.
​
permissions
string[]
List of native permissions to request from the user. Accepted values include "camera", "gps", "notifications", and others. Omit this field to request no permissions.

​
Example request

curl -X POST https://api.capwrapper.com/v1/builds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.example.com",
    "appName": "My Finance App",
    "bundleId": "com.example.financeapp",
    "version": "1.2.0",
    "permissions": ["camera", "notifications"]
  }'

​
Response

{
  "id": "bld_abc123xyz",
  "status": "queued",
  "createdAt": "2026-04-11T10:00:00Z",
  "url": "https://myapp.example.com",
  "appName": "My Finance App",
  "bundleId": "com.example.financeapp",
  "version": "1.2.0"
}
​
id
string
Unique build identifier. Use this to poll for status with GET /api/v1/builds/:id.
​
status
string
Initial build status. Always "queued" immediately after creation.
​
createdAt
string
ISO 8601 timestamp of when the build was created.

​
Get build status

GET /api/v1/builds/:id Returns the current status and details of a specific build. Poll this endpoint after creating a build to check when it completes.

​
Path parameters

​
id
string
required
The build ID returned by POST /api/v1/builds.

​
Build status values

ValueDescription
queuedBuild is waiting in the queue
buildingBuild is actively running
successBuild completed successfully — downloadUrl is available
failedBuild failed — check error field for details

​
Example request

curl https://api.capwrapper.com/v1/builds/bld_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (success)

{
  "id": "bld_abc123xyz",
  "status": "success",
  "createdAt": "2026-04-11T10:00:00Z",
  "completedAt": "2026-04-11T10:01:45Z",
  "downloadUrl": "https://cdn.capwrapper.com/builds/bld_abc123xyz/app-release.apk",
  "platform": "android"
}
​
id
string
Unique build identifier.
​
status
string
Current build status: queued, building, success, or failed.
​
createdAt
string
ISO 8601 timestamp of when the build was created.
​
completedAt
string
ISO 8601 timestamp of when the build finished. Present only when status is success or failed.
​
downloadUrl
string
Signed download URL for the compiled binary. Present only when status is success.
​
platform
string
Target platform: android or ios.

​
List all builds

GET /api/v1/builds Returns a paginated list of all your builds, sorted newest first.

​
Query parameters

​
limit
integer
Number of builds to return. Default: 20. Maximum: 100.
​
offset
integer
Number of builds to skip. Use with limit to paginate through results. Default: 0.

​
Example request

curl "https://api.capwrapper.com/v1/builds?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "builds": [
    {
      "id": "bld_abc123xyz",
      "status": "success",
      "appName": "My Finance App",
      "createdAt": "2026-04-11T10:00:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
​
builds
object[]
Array of build summary objects.
​
total
integer
Total number of builds in your account.
​
limit
integer
The limit value used for this response.
​
offset
integer
The offset value used for this response.