---
title: "API Request step"
section: "Step reference"
description: "How the SmartestQA API Request step works: adding a request or a curl command, body, authorization, params and headers, JSON path extraction, Send, and run-time rules."
url: https://docs.smartestqa.ai/en/automate-steps-api.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "api request step http rest get post put patch delete curl import json path extractor xpath status code header bearer token basic auth send response"
---
# Step reference: API Request step

The API Request step sends an HTTP request in the middle of a test: create test data before a UI flow, read a token, or check that the backend stored what the UI showed. It works in web, mobile and desktop projects.

## In short

**On this page you can**

- Add a request from your API Requests library or paste a curl command.
- Edit method, URL, body, authorization, params and headers for this step.
- Try the request with Send and click response values to save them.
- Save @status or a header into a variable and assert on it.
- Use variables in the URL, body, headers and token.

**How to use it**

1. Click API and pick a request in Select API Request , or use Create from curl .
2. Select the step and adjust the request in the right panel.
3. Click Send , then click a value in the response to add a JSON Paths row.
4. Name each row’s key, for example token ; later steps use {{tc:token}} .
5. Add an Assertion on {{tc:status}} so a 4xx or 5xx fails the test.

## Add an API step

1. **Open the picker**

   Click **API** in the step toolbar. The dialog **Select API Request** lists the requests of the project’s [**API Requests** library](https://docs.smartestqa.ai/en/api-requests-library.html). Search with “Search by name, URL or method...”.
2. **Pick a request, or paste curl**

   Click the add icon (**Add Step**) on a request’s row. Or click **Create from curl**, [paste a curl command](https://docs.smartestqa.ai/en/api-requests-in-tests.html#from-curl) and click **Create & Add**: a new API Request is created in the library and added as a step.

   The step shows the chip **API**. It gets [its own copy of the request](https://docs.smartestqa.ai/en/api-requests-in-tests.html#copy); editing the step does not change the library request.
3. **Adjust the request**

   Select the step. In the right panel edit [the method, the URL](https://docs.smartestqa.ai/en/api-requests-editor.html#request-line) and the tabs **Body**, **Authorization**, **Params** and **Headers**.
4. **Try it and save values**

   Click **Send**. Click a value in the response to add it under **JSON Paths**, and give it a key. See [Save values from the response](https://docs.smartestqa.ai/en/automate-steps-api.html#extract-values).
5. **Check the result**

   Add an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step) after the step. See [Check the status code](https://docs.smartestqa.ai/en/automate-steps-api.html#check-the-status).

## The request

| Part | Options | Notes |
| --- | --- | --- |
| Method | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | The runner sends only GET, POST, PUT, PATCH and DELETE. HEAD and OPTIONS can be saved but fail at run time with “Unsupported HTTP method”. |
| URL | Full address | Required (“API URL is required”). [Variables](https://docs.smartestqa.ai/en/automate-test-data.html#variables) allowed: `{{tc:baseUrl}}/orders/{{tc:orderId}}`. |
| Body | **form-data** rows, or **raw** as JSON, XML, HTML, Text or JavaScript | Variables are resolved in the body. The editor offers form-data, but runs ignore it: a run sends only the raw body, as JSON, and a body that is not JSON goes out as one JSON text in quotes ([Bodies in runs](https://docs.smartestqa.ai/en/api-requests-in-tests.html#body-in-runs)). |
| Authorization | **None**, [**Bearer Token**](https://docs.smartestqa.ai/en/api-requests-editor.html#authorization), [**Basic Auth**](https://docs.smartestqa.ai/en/api-requests-editor.html#authorization), [**Inherit from parent**](https://docs.smartestqa.ai/en/api-requests-editor.html#inherit-auth) | A token can be a variable: `{{tc:token}}`. The editor offers all four, but runs apply only **Bearer Token**; for a basic login, add an `Authorization` header ([Authorization in runs](https://docs.smartestqa.ai/en/api-requests-in-tests.html#auth-in-runs)). |
| Params | Key and value rows | Added to the URL as the query string. |
| Headers | Key and value rows | For example `Content-Type: application/json`. |

## Try the request with Send

**Send** runs the request now and shows the status code and the response. It is [sent from the SmartestQA server](https://docs.smartestqa.ai/en/api-requests-in-tests.html#run-differences), not from your [agent](https://docs.smartestqa.ai/en/agent-pool-agents.html), so it cannot reach APIs inside your company network; the test run itself can, when it [runs on your agent](https://docs.smartestqa.ai/en/schedule-where.html#agent).

- If the request contains variables, the dialog **Test values** asks for a value for each. “These variables get their value during the test run. Enter a value to try the request; values are not saved.” Empty fields are sent as empty text.
- To send from here, the URL must start with `http://` or `https://`. A URL that starts with a variable can still be saved and run.
- Messages: “Request successful”, “The request timed out (30s). The target did not respond.”, “Host not found. Please check the URL.”, “Connection refused. The target is not reachable.”, “The request could not be completed. Please try again.”

## Save values from the response

Each row under **JSON Paths** has a **key** (the [variable](https://docs.smartestqa.ai/en/automate-test-data.html#produce-variables) name) and a **path**. After the step runs, the value at the path is saved as `{{tc:key}}`.

- **Click to add.** After **Send**, “Click on any value in the response to extract its JSON path.” For XML responses, pick the node in the XML view.
- **Add by hand.** The plus icon adds an empty row: “Add JSON path manually (use when the API cannot be reached from here)”.
- The preview under a row shows what the path finds in the last response: “No match in the response - no value will be stored”, or how many matches there are (“the first one is used”).

| Path | Reads | Example result |
| --- | --- | --- |
| `data.token` or `$.data.token` | A JSON field | `eyJhbGciOi…` |
| `items.0.id` or `items[0].id` | A field of the first array item (counting from 0) | `1042` |
| `/order/status` | An XML node (paths starting with `/` are XPath) | `SHIPPED` |
| `@status` | The HTTP status code | `201` |
| `@header:Location` | A response header | `/orders/1042` |

Rows need both parts: “Fill in the key and the JSON path, or remove this row”. A path that cannot work is refused on save: “JSON path is invalid and cannot work at runtime”. If a path finds nothing at run time, the log notes that the key was not found and the variable is not set.

## Check the status code

> **Warning: Any HTTP answer is a passed step**
>
> The API step ends as SUCCESS for every status code, including 400, 401, 404 and 500. Only a timeout, an SSL error or a refused connection ends it as ERROR, and even then the test case continues. To make the test fail on a wrong status, save it and assert on it.

Example · create an order and check the answer

```text
Step 3  API        POST {{tc:baseUrl}}/api/orders
                   JSON Paths:  status ← @status      orderId ← data.id
Step 4  Assertion  actual {{tc:status}}   Equals        expected 201
Step 5  Assertion  actual {{tc:orderId}}  Is Not Empty
```

For negative tests, the same pattern checks that a call is refused: assert `{{tc:status}}` Equals `403`.

## At run time

- The request is sent from the machine that runs the test ([the server or your agent](https://docs.smartestqa.ai/en/schedule-where.html#run-environment)), with a fixed timeout of 30 seconds.
- TLS certificates are always verified. A self-signed certificate makes the step end as ERROR.
- [Variables](https://docs.smartestqa.ai/en/automate-test-data.html#resolution) in the URL, body, headers, query parameters and Bearer token are resolved first.
- The [report](https://docs.smartestqa.ai/en/report-steps.html#log-detail) keeps the request and the response of the step (the response is shortened to 5,000 characters).
- API steps are the only step type allowed next to JMeter and k6 steps. A load test can be generated from them; see [Load tests](https://docs.smartestqa.ai/en/automate-steps-load.html#generate).

## If something goes wrong

- [The step passed although the API returned an error](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-api-404-passes)
- [HEAD or OPTIONS fails at run time](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-api-head-options)
- [Send shows a timeout, host or connection error](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-api-send)
- [JSON path errors](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-json-path)
- [SSL or certificate errors](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-ssl)
