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

# API Runner

The **API Runner** is a built-in API testing tool — similar to Postman — that lets you create, organise, and execute API requests directly within TMS ONE. You can group requests into collections, use environment variables, write test scripts to validate responses, and integrate with GitHub or Azure DevOps for CI/CD workflows.

***

## Key features

* Create and organise API requests into **collections**
* Execute requests with full control over method, headers, body, and authentication
* Use **environment variables** to switch between dev, staging, and production
* Write **test scripts** to automatically validate responses
* Export collections to **GitHub or Azure DevOps** for CI/CD pipelines
* View full **execution history** in the Execution History page

***

## Getting started

### 1. Navigate to API Runner

From the left sidebar, click **API Runner** under your project.

### 2. Create a collection

Click **+ New Collection** in the sidebar and give it a name. Collections are used to group related API requests together — for example, all requests for a specific service or feature.

### 3. Add a request

Click **+ Add Request** under a collection. A blank request form will open in the main panel.

<Tip>
  You can also paste a cURL command to auto-populate the request. The API Runner will automatically parse the method, URL, headers, body, and authentication.
</Tip>

***

## Configuring a request

### Method and URL

Select the HTTP method (**GET**, **POST**, **PUT**, **DELETE**, **PATCH**) and enter the full URL.

You can use environment variables in the URL using double curly braces:

```text theme={null}
https://api.yourapp.com/{{environment}}/users
```

### Params tab

Add query string parameters as key-value pairs. Each parameter can be toggled on or off. Enabled parameters are automatically appended to the URL.

### Authorization tab

Choose from the following authentication types:

| Type             | Description                                          |
| ---------------- | ---------------------------------------------------- |
| **No Auth**      | No authentication (default)                          |
| **Basic Auth**   | Username and password — automatically base64 encoded |
| **Bearer Token** | Paste your token directly                            |
| **API Key**      | Key-value pair added to a header or query parameter  |

### Headers tab

Add custom request headers as key-value pairs. Each header can be toggled on or off. The `Content-Type` header is set automatically based on your body type.

### Body tab

Choose how to send the request body:

| Type            | When to use                                                |
| --------------- | ---------------------------------------------------------- |
| **None**        | GET requests with no body                                  |
| **Raw**         | JSON, XML, or plain text — includes a beautify JSON option |
| **Form Data**   | Multipart form submissions — supports file uploads         |
| **URL Encoded** | Standard HTML form submissions                             |

### Scripts tab

Write JavaScript test functions to automatically validate the response. All functions must start with `test`:

```javascript theme={null}
function testStatusCode() {
  tms.expect(response.status).toBe(200);
}

function testResponseBody() {
  tms.expect(response.data.success).toBe(true);
}
```

Test results show a pass ✅ or fail ❌ for each function after execution.

***

## Environment variables

Environments let you define reusable variables (like base URLs, tokens, or API keys) and switch between them without changing your requests.

### Creating an environment

1. Click the **environment dropdown** in the sidebar
2. Click **+ Create Environment**
3. Add key-value pairs (e.g. `baseUrl` = `https://api.staging.yourapp.com`)
4. Toggle individual variables on or off with the checkbox
5. Click **Save**

### Using variables in requests

Reference variables anywhere in your request using `{{variableName}}`:

```text theme={null}
URL:     https://{{baseUrl}}/users
Header:  Authorization: Bearer {{token}}
Body:    { "endpoint": "{{apiPath}}" }
```

Variables are substituted at the time of execution. If a variable isn't found, the `{{placeholder}}` is left unchanged.

***

## Sending a request

Click the **Send** button. The API Runner will:

1. Validate the URL format
2. Apply enabled query parameters
3. Inject authentication headers
4. Substitute environment variables
5. Send the request

### Reading the response

The response panel shows:

| Field       | Description                                               |
| ----------- | --------------------------------------------------------- |
| **Status**  | HTTP status code and message (e.g. 200 OK, 404 Not Found) |
| **Time**    | Request duration in milliseconds                          |
| **Size**    | Response payload size                                     |
| **Body**    | JSON (syntax highlighted), HTML (rendered), or plain text |
| **Headers** | Expandable panel showing all response headers             |

### Test results

If you've written test scripts, results appear in the **Scripts** tab after execution — showing which tests passed or failed and any error messages.

***

## Saving requests

Click **Save** to save the request to its collection. The request is stored with its configuration and latest response for future reference.

***

## Exporting to GitHub or Azure DevOps

You can push your collections to a version control repository in **Postman Collection v2.1 format** for use in CI/CD pipelines.

### GitHub

1. Click the **three-dot menu** on a collection
2. Select **Export to GitHub**
3. Connect your GitHub account if prompted
4. Select the organisation, repository, branch, and directory
5. Click **Push** — the collection is committed to the repo

### Azure DevOps

1. Select **Export to Azure** from the collection menu
2. Connect your Azure account if prompted
3. Select the organisation, project, repository, and branch
4. Click **Push**

<Note>
  Collections are exported in Postman Collection v2.1 format, making them compatible with Newman (Postman's CLI runner) for automated pipeline execution.
</Note>

***

## Viewing execution history

All past API Runner executions are available in the **Execution History** page under the **API tab**. From there you can:

* Search by request name
* View response status, time, and size
* Delete old results

See [Execution History](/qa/execution-history) for full details.

***

## Tips

<AccordionGroup>
  <Accordion title="Use environments to avoid hardcoding values">
    Never hardcode tokens, base URLs, or API keys directly in requests. Store them as environment variables so you can switch between environments without editing every request.
  </Accordion>

  <Accordion title="Name requests clearly">
    Use descriptive names like "Create User - Valid Payload" rather than "POST /users". This makes collections easier to read and helps when reviewing execution history.
  </Accordion>

  <Accordion title="Write test scripts for every request">
    Even a basic status code check (`tms.expect(response.status).toBe(200)`) adds value. It means every execution automatically validates the response, not just returns it.
  </Accordion>

  <Accordion title="Export collections early for CI/CD">
    Push your collection to GitHub or Azure DevOps as soon as it's stable. This gives your team an automated API test suite that can run on every deployment.
  </Accordion>
</AccordionGroup>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Execution History" icon="list" href="/qa/execution-history">
    View past API runner results in the API tab
  </Card>

  <Card title="Defect Management" icon="bug" href="/qa/defect-management">
    Log defects when API tests reveal issues
  </Card>
</CardGroup>