> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating API Tests

> Create an API application, configure access, and write focused tests for your HTTP endpoints

API tests start from natural-language instructions. QA.tech's API agent turns those instructions into HTTP requests and executable validation code, then records the results for review.

## Create an API Application

**1. Open Applications & Envs**

Go to [**Settings → Applications &
Envs**](https://app.qa.tech/current-project/settings/applications) and click
**Create Application**.

**2. Choose API application**

Enter an application name and select **API application**. API applications
are intended for REST and HTTP APIs.

**3. Add the first environment**

Enter an environment name and the API's HTTPS base URL, such as
`https://api.staging.example.com`. The first environment becomes the
application's default.

**4. Create the application**

Optionally mark the environment as production or limit its concurrent tests,
then click **Create Application**.

Add more environments when the same tests should run against multiple deployments, such as staging and production. Every API environment URL must use HTTPS and be reachable from the public internet.

## Configure Authentication and Test Data

Create reusable values under **Settings → Configs**, then assign them to the test under **Settings → Configs**.

**1. Create an API Key or Custom Fields config**

Go to **Settings → Configs**, click **Add config**, and choose **API Key**
for a secret token, or **Custom Fields** for non-secret IDs and payload
data. Give the config a descriptive name such as `API credentials`.

**2. Add the required values**

For an API Key config, paste the test key. For Custom Fields, add one field
for each value the agent needs.

| Key | Example value | Intended use |
| - | - | - |
| `accountId` | `acct_test_123` | Request path or body |

**3. Assign the config**

Open the API test, select **Settings → Configs**, and attach the new config.

**4. Reference the configured credentials**

In the Goal or Steps, write an instruction such as "Authenticate using the
configured API credentials." Do not paste the values into the test
instructions.

QA.tech provides API Key and Custom Fields values to the sandbox as environment variables. The agent-generated code uses them to construct request headers, paths, or bodies.

## Write a Focused API Test

Click **Add Test Case**, choose **Create Test Manually**, and complete these fields:

| Field | What to write |
| - | - |
| **Application** | Select the API application you created |
| **Name** | A short behavior name, such as `Create and retrieve an order` |
| **Goal** | The API operation to perform |
| **Expected result** | The exact status codes, response shape, and named values that determine success |
| **Configs** | Authentication headers and reusable test data |
| **Dependencies** | Optional tests that must finish before this test starts |

Click **Generate test** to create the test and start its first run. QA.tech then opens the test editor, where you can review the run and add optional Steps to make later runs more prescriptive.

API tests do not use **Start path** or **Agent Cache**. The environment base URL replaces the start path, and every run generates the code needed for the current API behavior.

Dependencies currently control execution order for API tests. They do not pass browser state or output data into the API agent.

### Example Test

| Field | Example |
| - | - |
| **Name** | `Create and retrieve an order` |
| **Goal** | Create an order with quantity 2, then retrieve the created order |
| **Expected result** | The create request returns 201 with a string `id`. Fetching that ID returns 200 with `quantity` equal to 2. |

After the first run, you can add these optional Steps:

1. Send `POST /orders` with a quantity of 2.
2. Read the order ID from the response.
3. Send `GET /orders/{id}` and verify the returned order.

The agent can save response bodies, parse JSON, reuse the returned ID, and run assertions in the sandbox. You do not need to provide shell, JavaScript, or Python code.

## Write Reliable Instructions

| Prefer | Avoid |
| - | - |
| Name endpoint paths, methods, and expected status codes | "Check that the API works" |
| Describe required fields and their types | Comparing every field in the response |
| Reuse an ID returned by the API | Hardcoding a generated ID |
| State the expected error for a negative test | Treating every `4xx` response as a test failure |
| Keep one test focused on one behavior | Combining an entire API suite into one test |

For negative tests, state the expected rejection explicitly. For example: "Calling `GET /account` with an expired token returns 401 and an error object containing a string `message`."

## Run and Review

The first run starts when you click **Generate test**. For later changes in the test editor, click **Save & Run**. While the test runs, the Action Log shows the agent's named steps.

Select a completed step to review:

* The **network icon** for request and response details, status codes, headers, bodies, and **Copy as cURL**
* The **terminal icon** for the generated command, standard output, standard error, and exit status
* The final action for the Passed or Failed verdict and plain-language summary

An API run has no browser stream, screenshots, or video. The captured HTTP exchanges and command output are the test evidence.

> [!TIP]
>
> Error means the run ended without a test verdict, for example because the
> sandbox could not start or the agent exhausted its execution budget. Open the
> result details for the specific cause. An API behavior that does not match the
> expected result is reported as Failed.

## Related documentation

* [Understand API testing](https://docs.qa.tech/core-concepts/api-testing)
* [Configure reusable test data](https://docs.qa.tech/core-concepts/configs.md)
* [Organize applications and environments](https://docs.qa.tech/core-concepts/applications-and-environments.md)
* [Review tests and results](https://docs.qa.tech/core-concepts/tests-and-results.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.