> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capwrapper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, List, and Check Build Status

> Create new Capwrapper build jobs, poll for status, and list all your builds using the REST API. Full parameter and response reference.

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](/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

<ParamField body="url" type="string" required>
  The public HTTPS URL of your web app. Must be publicly accessible at build time.
</ParamField>

<ParamField body="appName" type="string" required>
  Display name for your app. This is the name shown on the device home screen and in the app store listing.
</ParamField>

<ParamField body="bundleId" type="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.
</ParamField>

<ParamField body="version" type="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.
</ParamField>

<ParamField body="permissions" type="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.
</ParamField>

### Example request

```bash theme={null}
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

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Unique build identifier. Use this to poll for status with `GET /api/v1/builds/:id`.
</ResponseField>

<ResponseField name="status" type="string">
  Initial build status. Always `"queued"` immediately after creation.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the build was created.
</ResponseField>

***

## 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

<ParamField path="id" type="string" required>
  The build ID returned by `POST /api/v1/builds`.
</ParamField>

### Build status values

| Value      | Description                                               |
| ---------- | --------------------------------------------------------- |
| `queued`   | Build is waiting in the queue                             |
| `building` | Build is actively running                                 |
| `success`  | Build completed successfully — `downloadUrl` is available |
| `failed`   | Build failed — check `error` field for details            |

### Example request

```bash theme={null}
curl https://api.capwrapper.com/v1/builds/bld_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (success)

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Unique build identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Current build status: `queued`, `building`, `success`, or `failed`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the build was created.
</ResponseField>

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp of when the build finished. Present only when `status` is `success` or `failed`.
</ResponseField>

<ResponseField name="downloadUrl" type="string">
  Signed download URL for the compiled binary. Present only when `status` is `success`.
</ResponseField>

<ResponseField name="platform" type="string">
  Target platform: `android` or `ios`.
</ResponseField>

***

## List all builds

**`GET /api/v1/builds`**

Returns a paginated list of all your builds, sorted newest first.

### Query parameters

<ParamField query="limit" type="integer">
  Number of builds to return. Default: `20`. Maximum: `100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of builds to skip. Use with `limit` to paginate through results. Default: `0`.
</ParamField>

### Example request

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

### Response

```json theme={null}
{
  "builds": [
    {
      "id": "bld_abc123xyz",
      "status": "success",
      "appName": "My Finance App",
      "createdAt": "2026-04-11T10:00:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
```

<ResponseField name="builds" type="object[]">
  Array of build summary objects.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of builds in your account.
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value used for this response.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value used for this response.
</ResponseField>