Skip to main content
The nunu.ai Public API allows you to programmatically interact with your projects, manage test runs, and upload builds. Use it to integrate nunu.ai into your CI/CD pipelines, build custom tooling, or automate your testing workflows.

​
Base URL

All API requests should be made to: 
https://nunu.ai/api/v1

​
Available Endpoints

Runs

Start tests, monitor progress, retrieve results, and access bug reports

Builds

Upload and manage builds in nunu.ai’s cloud storage

​
Runs Endpoints

EndpointMethodDescription
/runsGETList runs with filtering and pagination
/runsPOSTStart a test or test plan
/runs/{runId}GETGet detailed run information with artifacts
/runs/{runId}/bugsGETList bugs found in a run
/runs/stopPOSTStop one or more running tests

​
Builds Endpoints

EndpointMethodDescription
/builds/uploadPOSTInitiate a build upload
/builds/upload/partsGETGet presigned URLs for multipart upload
/builds/upload/completePOSTComplete an upload
/builds/uploadDELETECancel an in-progress upload

​
Authentication

All API requests require authentication via an API key. Include your API key in the X-Api-Key header: 
X-Api-Key: YOUR_API_TOKEN
Get your API keys from Project Admin → API Keys in the nunu.ai dashboard. Each key requires specific permissions based on the endpoints you want to access.

Learn more about authentication

API key management, permissions, and security best practices

​
Permissions

API keys are scoped to specific permissions. Use only the permissions you need:
PermissionDescriptionRequired For
project:read-runsRead run data, artifacts, and bugsListing runs, getting run details
project:operate-runsStart and stop test runsStarting tests, stopping runs
project:manage-build-storageUpload and manage buildsAll build upload operations

​
Response Format

All responses are returned as JSON. Successful responses typically include: 
{
  "data": { ... },
  "pagination": { ... }  // For paginated endpoints
}
Error responses follow this format: 
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { ... }
}

​
HTTP Status Codes

CodeDescription
200Success
201Created (for POST requests that create resources)
207Multi-Status (partial success for batch operations)
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid API key
403Forbidden - API key lacks required permission
404Not Found - Resource doesn’t exist
402Payment Required - Quota exceeded
413Payload Too Large - File exceeds limits
500Internal Server Error

​
Rate Limits

The API uses rate limiting to ensure fair usage. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Implement exponential backoff when retrying requests.

​
SDKs and Tools

While you can use the API directly, we recommend using our official tools for common use cases:

CLI Tool

Upload builds from any environment

GitHub Action

Integrate with GitHub Actions