Skip to main content

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.

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

Artifacts

List and download recordings, logs, and deliverables produced by a run

Knowledge

Read knowledge files attached to your project, agents, and test cases

​
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

​
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.
EndpointMethodDescription
/runs/{runId}/artifactsGETList all artifacts produced by a run
/runs/{runId}/artifacts/{filename}GETDownload 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.
EndpointMethodDescription
/file-storage/{projectId}GETList project files, optionally combined with agent/test-case scopes
/file-storage/{projectId}/projectGETList project-scope knowledge files
/file-storage/{projectId}/agent/{agentId}GETList agent-scope knowledge files
/file-storage/{projectId}/test_case/{testCaseId}GETList 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: 
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