curl -X POST "https://nunu.ai/api/v1/project/your-project-id/tests" \
-H "X-Api-Key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"test": {
"name": "Sanity smoke",
"test_type": "verification",
"tags": ["smoke"],
"incident_auto_approve": false,
"quarantined": false,
"testrail": null,
"max_seconds": 1800,
"players_by_key": {
"1": {
"name": "P1",
"agent_config_id": null,
"game_funcs_config_id": null,
"items_by_key": {
"1": {
"type": "step",
"goal": "Reach the main menu",
"expected_results": [
{ "expected": "the main menu is visible" },
{ "expected": "no loading spinner remains on screen" }
],
"screenshots": 1,
"pause_game": false,
"performance_monitoring": false,
"hint_manual": []
}
},
"item_order": ["1"]
}
},
"player_order": ["1"]
},
"folder_path": "regression/smoke"
}'
{
"id": "a5060a07-d386-4269-98ce-b33fb894201e",
"project_id": "test",
"name": "Sanity smoke",
"version": 0,
"tags": ["smoke"],
"incident_auto_approve": false,
"test_type": "verification",
"quarantined": false,
"testrail": null,
"source": "repository",
"players_by_key": { "...": "..." },
"player_order": ["1"]
}
{
"error": "invalid request: test.name: Required"
}
Tests
Create Test
Create a new test case in the authenticated project.
POST
/
project
/
{projectId}
/
tests
curl -X POST "https://nunu.ai/api/v1/project/your-project-id/tests" \
-H "X-Api-Key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"test": {
"name": "Sanity smoke",
"test_type": "verification",
"tags": ["smoke"],
"incident_auto_approve": false,
"quarantined": false,
"testrail": null,
"max_seconds": 1800,
"players_by_key": {
"1": {
"name": "P1",
"agent_config_id": null,
"game_funcs_config_id": null,
"items_by_key": {
"1": {
"type": "step",
"goal": "Reach the main menu",
"expected_results": [
{ "expected": "the main menu is visible" },
{ "expected": "no loading spinner remains on screen" }
],
"screenshots": 1,
"pause_game": false,
"performance_monitoring": false,
"hint_manual": []
}
},
"item_order": ["1"]
}
},
"player_order": ["1"]
},
"folder_path": "regression/smoke"
}'
{
"id": "a5060a07-d386-4269-98ce-b33fb894201e",
"project_id": "test",
"name": "Sanity smoke",
"version": 0,
"tags": ["smoke"],
"incident_auto_approve": false,
"test_type": "verification",
"quarantined": false,
"testrail": null,
"source": "repository",
"players_by_key": { "...": "..." },
"player_order": ["1"]
}
{
"error": "invalid request: test.name: Required"
}
Permission Required:
project:edit-teststest depends on
test_type; this endpoint accepts the same verification / discovery /
task variants returned by Get Test.
By default, requests that include shared collection steps inline are
rejected with
400. Pass shared_collection_steps_mode=drop to silently
drop the inline steps (they will be resolved from the shared step
collection at run time).Query Parameters
boolean
default:"true"
Whether shared collection steps are expanded inline in the response.
string
default:"error"
How to handle shared collection items that contain inline steps:
error (reject) or drop (silently strip the inline steps).Request Body
TestCase
required
Test definition.
id may be omitted to have one generated. version is
ignored on create. See Get Test for the
detailed shape.Expected results for verification steps. Use
expected_results to give a
step one or more independent checks. It accepts:- a single string — one result,
- a list of strings — one result per element,
- a list of
{ "expected": "..." }objects (forward-compatible form).
finish_condition (single string) is still accepted as an
alias for a single result and is ignored when expected_results is present.string
Folder path to place the test in (e.g.
"regression/smoke"). null or
"/" places it at the project root. Mutually exclusive with folder_id.string
Pre-resolved folder UUID. Mutually exclusive with
folder_path.Test-level time budget
The runtime budget is configured on the test itself, not on individual steps or players. There is no per-run override surface — to change the budget, edit the test (or create a new version).| Test type | Allowed fields | Default | Notes |
|---|---|---|---|
verification | max_seconds | 19800 (5.5h) | min_seconds is rejected — verification has no minimum runtime. |
discovery | min_seconds, max_seconds | 3600–10800 (1h–3h) | Both bounds optional; defaults apply when omitted. |
task | min_seconds, max_seconds | 0–19800 (0–5.5h) | Both bounds optional; defaults apply when omitted. |
discovery and task the server validates min_seconds <= max_seconds
against the effective budget — i.e. caller-supplied values after
defaults are applied. Supplying just one bound that conflicts with the
default for the other (e.g. min_seconds: 14400 on a discovery create with
no max_seconds) is rejected with 400; either supply the other bound
explicitly, or pick a value that fits inside the default range.
The hard upper bound for any single run is 5.5h (19800 seconds).
Test-level memory
memory controls whether the agent may read and write memory files across runs
of this test. It applies to every test type and requires the project’s knowledge
feature to be enabled.
| Value | Behavior |
|---|---|
omitted / null | Auto — inherit the project’s default memory setting. |
disabled | Memory is off for this test. |
read_write | The agent may read and write memory files across runs of this test. |
read_only | The agent may read but not write memory files. |
memory to leave it
unchanged, send null to reset it to auto, or send an explicit value to
override. When the project’s knowledge feature is disabled, memory is always off
regardless of this setting.
Response
Returns the newly created test with status201. The response shape is
identical to Get Test.
curl -X POST "https://nunu.ai/api/v1/project/your-project-id/tests" \
-H "X-Api-Key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"test": {
"name": "Sanity smoke",
"test_type": "verification",
"tags": ["smoke"],
"incident_auto_approve": false,
"quarantined": false,
"testrail": null,
"max_seconds": 1800,
"players_by_key": {
"1": {
"name": "P1",
"agent_config_id": null,
"game_funcs_config_id": null,
"items_by_key": {
"1": {
"type": "step",
"goal": "Reach the main menu",
"expected_results": [
{ "expected": "the main menu is visible" },
{ "expected": "no loading spinner remains on screen" }
],
"screenshots": 1,
"pause_game": false,
"performance_monitoring": false,
"hint_manual": []
}
},
"item_order": ["1"]
}
},
"player_order": ["1"]
},
"folder_path": "regression/smoke"
}'
{
"id": "a5060a07-d386-4269-98ce-b33fb894201e",
"project_id": "test",
"name": "Sanity smoke",
"version": 0,
"tags": ["smoke"],
"incident_auto_approve": false,
"test_type": "verification",
"quarantined": false,
"testrail": null,
"source": "repository",
"players_by_key": { "...": "..." },
"player_order": ["1"]
}
{
"error": "invalid request: test.name: Required"
}
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
Whether shared collection steps are expanded inline in the response
How to treat shared collection items with inline steps
Available options:
error, drop Body
application/json
Full test case body. Shape varies by test_type (verification, discovery, task); see the docs page for the exact shape.
Show child attributes
Show child attributes
Folder path placement. "/" or null = root. Mutually exclusive with folder_id.
Folder UUID placement. Mutually exclusive with folder_path.
Response
Test created
Full test case body. Shape varies by test_type (verification, discovery, task); see the docs page for the exact shape.
Available options:
verification, discovery, task Available options:
repository, bot Test-level minimum runtime in seconds. Allowed for discovery and task only; sending this on a verification test is rejected with 400. Defaults when omitted: discovery=3600 (1h), task=0. Must be ≤ max_seconds (validated against the effective budget after defaults are applied).
Required range:
0 <= x <= 19800Test-level maximum runtime in seconds. Hard ceiling for any single run is 19800 (5.5h). Defaults when omitted: verification=19800 (5.5h), discovery=10800 (3h), task=19800 (5.5h).
Required range:
0 <= x <= 19800Test-level memory override. null or omitted means "auto" — inherit the project's default memory setting. disabled turns memory off for this test; read_write lets the agent read and write memory files across runs. Requires the project's knowledge feature to be enabled. Applies to all test types. On read it is always present (null = auto); on a patch, omit it to leave it unchanged.
Available options:
disabled, read_only, read_write