curl -X GET "https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10" \
-H "X-Api-Key: YOUR_API_TOKEN"
const response = await fetch(
"https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10",
{
headers: {
"X-Api-Key": process.env.NUNU_API_TOKEN,
},
}
);
const data = await response.json();
import requests
import os
response = requests.get(
"https://nunu.ai/api/v1/project/your-project-id/builds",
headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]},
params={
"deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
"extra_app_number": 1,
"tags": "release,candidate",
"page": 0,
"page_size": 10,
}
)
data = response.json()
{
"data": [
{
"build_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Production Build v1.2.3",
"platform": "android",
"status": "OK",
"project_id": "your-project-id",
"filename": "app-release.apk",
"size": 52428800,
"pinned": true,
"nunu_sdk": true,
"tags": ["version:1.2.3", "env:production"],
"created_at": "2026-03-03T15:50:19.544603+00:00",
"last_used": "2026-03-10T10:30:00.000000+00:00",
"description": "Release build for production"
}
],
"pagination": {
"page": 0,
"page_size": 10,
"total_count": 25,
"total_pages": 3
}
}
Builds
List Builds
Retrieve a paginated list of builds for your project. Without deployment_config_id, results are from Build Storage. With a deployment config, the selected app’s source determines the results: Build Storage builds satisfy the app’s platform, file/ZIP format, required tags, and ready status (OK), while an external-platform source returns builds from that platform. SDK and WAIT_SDK restrict main-app Build Storage discovery to SDK builds; Build Storage extra apps have no automatic SDK restriction. For external-platform results, status, pinned, nunu_sdk, platform, and tags filters are unsupported and return 400; pagination remains available.
GET
/
project
/
{projectId}
/
builds
curl -X GET "https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10" \
-H "X-Api-Key: YOUR_API_TOKEN"
const response = await fetch(
"https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10",
{
headers: {
"X-Api-Key": process.env.NUNU_API_TOKEN,
},
}
);
const data = await response.json();
import requests
import os
response = requests.get(
"https://nunu.ai/api/v1/project/your-project-id/builds",
headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]},
params={
"deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
"extra_app_number": 1,
"tags": "release,candidate",
"page": 0,
"page_size": 10,
}
)
data = response.json()
{
"data": [
{
"build_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Production Build v1.2.3",
"platform": "android",
"status": "OK",
"project_id": "your-project-id",
"filename": "app-release.apk",
"size": 52428800,
"pinned": true,
"nunu_sdk": true,
"tags": ["version:1.2.3", "env:production"],
"created_at": "2026-03-03T15:50:19.544603+00:00",
"last_used": "2026-03-10T10:30:00.000000+00:00",
"description": "Release build for production"
}
],
"pagination": {
"page": 0,
"page_size": 10,
"total_count": 25,
"total_pages": 3
}
}
Permission Required:
project:manage-build-storagedeployment_config_id, this lists Build Storage builds. With a deployment
config, the selected app’s source determines the results: Build Storage builds
are filtered by the app’s requirements, while an external-platform source
returns that platform’s builds. Pagination is supported for both.
Query Parameters
string
Filter by build status (e.g.,
OK, UNHEALTHY)boolean
Filter by pinned status:
true for pinned builds only, false for non-pinned onlyboolean
Filter by nunu SDK integration:
true for SDK builds only, false for non-SDK onlystring
Filter by platform:
windows, android, ios-nativestring
Filter by tags (comma-separated). All specified tags must match. Example:
tags=release,candidatestring
Resolve builds for the selected app in this deployment config. The config
must belong to the project. Build Storage results must match the app’s
platform and file format, include its
required_tags, and be ready (OK).
If the main app requires nunu SDK, results must include the SDK. If the app
uses an external-platform source, results come from that platform instead.
A missing or foreign deployment config returns 404.integer
Select a Build Storage extra app (
1–3) from summary.extra_apps on the
deployment config. Requires deployment_config_id. Omit it to select the
main app. Extra apps are filtered by their own platform, file format, and
required_tags; the main app’s SDK requirement does not apply to them. An
invalid extra app number or an app with an unsupported build source returns
400.For Build Storage, config requirements are applied together with
caller-supplied filters: filters can narrow results but cannot broaden them.
When the selected app uses an external platform,
status, pinned,
nunu_sdk, platform, and tags are unsupported and return 400. Page
and page_size continue to work.integer
default:"0"
Page number (0-indexed)
integer
default:"20"
Results per page (1-100)
Response
Build[]
required
Array of build objects
object
required
Build Storage Build Object
string
required
Unique identifier for the Build Storage build (UUID). Use this value as
build_id or as a value in extra_build_ids when starting a run with a
Build Storage source.string
required
Project for which builds were listed
string
required
Build name
string
required
Target platform
string
required
Build status, such as
OK (ready) or UNHEALTHYstring
required
Original file name
integer
required
File size in bytes
boolean
required
Whether the build is pinned (protected from auto-deletion)
boolean
required
Whether the build includes nunu SDK integration
string[]
required
Tags associated with this build
string
required
ISO 8601 timestamp when the build was created
string
ISO 8601 timestamp when the build was last used in a run
string
Build description
External Platform Build Object
When the selected app uses an external platform, each item contains only these fields. Build Storage fields such asfilename, status, size, pinned,
nunu_sdk, tags, last_used, and description are omitted.
string
required
Opaque build ID returned by the external platform. Use it as
build_id when
starting a run with this deployment config.string
required
Project for which builds were listed
string
required
Build name
string
required
Always
external-platformstring | null
required
ISO 8601 creation timestamp, or
null if the external platform does not
provide onestring
External platform build version, when available
curl -X GET "https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10" \
-H "X-Api-Key: YOUR_API_TOKEN"
const response = await fetch(
"https://nunu.ai/api/v1/project/your-project-id/builds?deployment_config_id=456e7890-e89b-12d3-a456-426614174000&extra_app_number=1&tags=release,candidate&page=0&page_size=10",
{
headers: {
"X-Api-Key": process.env.NUNU_API_TOKEN,
},
}
);
const data = await response.json();
import requests
import os
response = requests.get(
"https://nunu.ai/api/v1/project/your-project-id/builds",
headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]},
params={
"deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
"extra_app_number": 1,
"tags": "release,candidate",
"page": 0,
"page_size": 10,
}
)
data = response.json()
{
"data": [
{
"build_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Production Build v1.2.3",
"platform": "android",
"status": "OK",
"project_id": "your-project-id",
"filename": "app-release.apk",
"size": 52428800,
"pinned": true,
"nunu_sdk": true,
"tags": ["version:1.2.3", "env:production"],
"created_at": "2026-03-03T15:50:19.544603+00:00",
"last_used": "2026-03-10T10:30:00.000000+00:00",
"description": "Release build for production"
}
],
"pagination": {
"page": 0,
"page_size": 10,
"total_count": 25,
"total_pages": 3
}
}
Authorizations
API key for authentication
Path Parameters
The project ID. You can copy it from the project settings page or the project URL in the dashboard.
Query Parameters
Deployment config UUID from this project. Selects its main app unless extra_app_number is supplied. The selected app's source determines whether results come from Build Storage or an external platform.
One-based Build Storage extra app number in the saved deployment config. Requires deployment_config_id; omission targets the main app.
Required range:
1 <= x <= 3Filter by build status (e.g., OK, UNHEALTHY). Unsupported when deployment_config_id selects an external platform; returns 400.
Filter by pinned status. Unsupported when deployment_config_id selects an external platform; returns 400.
Filter by nunu SDK integration. Unsupported when deployment_config_id selects an external platform; returns 400.
Filter by platform. Unsupported when deployment_config_id selects an external platform; returns 400.
Available options:
windows, macos, linux, android, ios-native, ios-simulator, xbox, playstation Filter by tags (comma-separated). All specified tags must match. Unsupported when deployment_config_id selects an external platform; returns 400.
Page number (0-indexed)
Results per page (1-100)
Required range:
1 <= x <= 100