> ## 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

<Steps>
  <Step title="Open Applications & Envs">
    Go to [**Settings → Applications &
    Envs**](https://app.qa.tech/current-project/settings/applications) and click
    **Create Application**.
  </Step>

  <Step title="Choose API application">
    Enter an application name and select **API application**. API applications
    are intended for REST and HTTP APIs.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Create the application">
    Optionally mark the environment as production or limit its concurrent tests,
    then click **Create Application**.
  </Step>
</Steps>

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**.

<Steps>
  <Step title="Create a Custom Fields config">
    Go to **Settings → Configs**, click **Add config**, and choose **Custom
    Fields**. Give the config a descriptive name such as `API credentials`.
  </Step>

  <Step title="Add the required values">
    Add one field for each value the agent needs. Use the header name as the key
    when a value belongs in a request header.

    | Key             | Example value       | Intended use         |
    | --------------- | ------------------- | -------------------- |
    | `Authorization` | `Bearer test-token` | Authorization header |
    | `X-API-Key`     | `test-api-key`      | API key header       |
    | `accountId`     | `acct_test_123`     | Request path or body |
  </Step>

  <Step title="Assign the config">
    Open the API test, select **Settings → Configs**, and attach the new config.
  </Step>

  <Step title="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.
  </Step>
</Steps>

QA.tech provides 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.
</Tip>

## Related

* [Understand API testing](/core-concepts/api-testing)
* [Configure reusable test data](/core-concepts/configs)
* [Organize applications and environments](/core-concepts/applications-and-environments)
* [Review tests and results](/core-concepts/tests-and-results)