# Zuar Runner API

Almost every action performed in the Zuar Runner UI has a corresponding REST API
endpoint. This means you can programmatically create and manage jobs and use
Zuar Runner as a data source.

All of the information below references Zuar Runner's REST API. Zuar Runner also contains
a [Zuar WAF](https://www.zuar.com/help/waf/) and it's corresponding "auth" API
documentation is [here](https://www.zuar.com/help/waf/auth-api/).

If you are looking for information related to authentication endpoints like
adding and removing users, editing users, etc., please see [Zuar Runner Auth API
page](/api/auth).

## Base URL

There are currently 2 versions of the Zuar Runner API. By exploring Zuar Runner's Swagger
Docs, you can determine which version of the endpoint is
required. `https://{runner_url}/docs`

Version 1

`https://{runner_url}/api/`

Version 2

`https://{runner_url}/api/v2`

## Authentication

Zuar Runner's API uses a revocable API key for access. This is consistent across all
version of the Zuar Runner API.

`https://{runner_url}/api/v2/{endpoint}?API_KEY={api_key}`

### API Key

1. Click on the **Settings** menu.
2. Under the **About** tab on the settings page there is a **Product
   Configuration** section. Locate the **API Key** area and click on the edit
   icon.
3. View, generate, and regenerate Zuar Runner's API key.

   .. image:: assets/mitto__api_key.png
      :alt: generate mitto api key

## Authorization

The Zuar Runner API key has full admin access.

## Endpoints and Methods

As mentioned above, Zuar Runner has [Swagger](https://swagger.io/) documentation at
`https://{runner_url}/docs`. You can see all the API endpoints and test them
using the Swagger UI.


.. image:: assets/mitto__swagger.png
   :alt: mitto swagger docs

.. image:: assets/mitto__swagger1.png

## Responses

Zuar Runner's APIs return data in JSON format. Here is an example from `/files`: 
```json
{
  files: [
	{
	  name: "example.csv",
	  size: 7874,
	  size_hr: "7.7 KiB",
	  mtime: {
		utc: "2019-08-20T20:49:22.256707+00:00",
		epoch: 1566334162.256707,
		local: "2019-08-20T15:49:22.256707-05:00",
		local_hr: "8-20 3:49:22PM CDT"
	  },
	  mode: "-rw-r--r--"
	}
  ],
  count: 1,
  size: 7874,
  display-size: "7.7 KiB"
}
```    

## Example Requests

Using a cUrl request to start a job. The request below will trigger job ID 70:

```bash
curl --location --request POST 'https://mitto.zuarbase.net/api/v2/jobs/70/:actions?API_KEY={addkeyhere}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "action": "START"
}'
```