> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.nunu.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Programmatically interact with nunu.ai to manage test runs, upload builds, and integrate with your CI/CD pipelines
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
Requests to the main API are scoped to a project. The base URL includes the ID of the project you are working with:
```
https://nunu.ai/api/v1/project/{projectId}
```
You can copy the project ID from the project settings page or from the project URL in the dashboard.
The [artifacts](/api-reference/artifacts/list-artifacts) and [knowledge](/api-reference/knowledge/list-files) endpoints are the exception: they are served by the bouncer service at `https://bouncer.nunu.ai` and do not use this base URL. See their sections below for details.
Requests without the `/project/{projectId}` prefix (for example `https://nunu.ai/api/v1/runs`) keep working for existing integrations that use project API keys. The project is inferred from the key. New integrations should use the project scoped form shown here. Organization API keys only work with the project scoped form.
## Available Endpoints
Start tests, monitor progress, retrieve results, and access bug reports
Upload and manage builds in nunu.ai's cloud storage
List and download recordings, logs, and deliverables produced by a run
Read knowledge files attached to your project, agents, and test cases
### Runs Endpoints
| Endpoint | Method | Description |
| ----------------------------------------------------- | ------ | ------------------------------------------- |
| [`/runs`](/api-reference/runs/list-runs) | GET | List runs with filtering and pagination |
| [`/runs`](/api-reference/runs/start-run) | POST | Start a test or test plan |
| [`/runs/{runId}`](/api-reference/runs/get-run) | GET | Get detailed run information with artifacts |
| [`/runs/{runId}/bugs`](/api-reference/runs/list-bugs) | GET | List bugs found in a run |
| [`/runs/stop`](/api-reference/runs/stop-runs) | POST | Stop one or more running tests |
### Builds Endpoints
| Endpoint | Method | Description |
| ------------------------------------------------------------------ | ------ | --------------------------------------- |
| [`/builds/upload`](/api-reference/builds/initiate-upload) | POST | Initiate a build upload |
| [`/builds/upload/parts`](/api-reference/builds/get-upload-parts) | GET | Get presigned URLs for multipart upload |
| [`/builds/upload/complete`](/api-reference/builds/complete-upload) | POST | Complete an upload |
| [`/builds/upload`](/api-reference/builds/cancel-upload) | DELETE | Cancel an in-progress upload |
### Artifacts Endpoints
Served by the **bouncer** service at `https://bouncer.nunu.ai` (not `nunu.ai/api/v1`). Authenticated with the same `X-Api-Key` header.
| Endpoint | Method | Description |
| ----------------------------------------------------------------------------- | ------ | ------------------------------------ |
| [`/runs/{runId}/artifacts`](/api-reference/artifacts/list-artifacts) | GET | List all artifacts produced by a run |
| [`/runs/{runId}/artifacts/{filename}`](/api-reference/artifacts/get-artifact) | GET | Download a single artifact file |
### Knowledge Endpoints
Served by the **bouncer** service at `https://bouncer.nunu.ai` (not `nunu.ai/api/v1`). Authenticated with the same `X-Api-Key` header.
| Endpoint | Method | Description |
| --------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------- |
| [`/file-storage/{projectId}`](/api-reference/knowledge/list-files) | GET | List project files, optionally combined with agent/test-case scopes |
| [`/file-storage/{projectId}/project`](/api-reference/knowledge/list-project-files) | GET | List project-scope knowledge files |
| [`/file-storage/{projectId}/agent/{agentId}`](/api-reference/knowledge/list-agent-files) | GET | List agent-scope knowledge files |
| [`/file-storage/{projectId}/test_case/{testCaseId}`](/api-reference/knowledge/list-test-case-files) | GET | List test-case-scope knowledge files |
## Authentication
All API requests require authentication via an API key. Include your API key in the `X-Api-Key` header:
```http theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
X-Api-Key: YOUR_API_TOKEN
```
Get your API keys from **Project Admin → API Keys** in the nunu.ai dashboard. Organization admins can also create organization API keys under **Org Admin → API Keys**; these keys work across all projects of the organization. Each key requires specific permissions based on the endpoints you want to access.
API key management, permissions, and security best practices
## Permissions
API keys are scoped to specific permissions. Use only the permissions you need:
| Permission | Description | Required For |
| ------------------------------ | ---------------------------------- | --------------------------------- |
| `project:read-runs` | Read run data, artifacts, and bugs | Listing runs, getting run details |
| `project:operate-runs` | Start and stop test runs | Starting tests, stopping runs |
| `project:manage-build-storage` | Upload and manage builds | All build upload operations |
## Response Format
All responses are returned as JSON. Successful responses typically include:
```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"data": { ... },
"pagination": { ... } // For paginated endpoints
}
```
Error responses follow this format:
```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"error": "Error message",
"code": "ERROR_CODE",
"details": { ... }
}
```
## HTTP Status Codes
| Code | Description |
| ----- | --------------------------------------------------- |
| `200` | Success |
| `201` | Created (for POST requests that create resources) |
| `207` | Multi-Status (partial success for batch operations) |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Missing or invalid API key |
| `403` | Forbidden - API key lacks required permission |
| `404` | Not Found - Resource doesn't exist |
| `402` | Payment Required - Quota exceeded |
| `413` | Payload Too Large - File exceeds limits |
| `500` | Internal 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:
Upload builds from any environment
Integrate with GitHub Actions