consul/website/content/docs/nia/api.mdx

---
layout: docs
page_title: Consul-Terraform-Sync API
sidebar_title: API
description: >-
  How to use the Consul-Terraform-Sync API
---

# Consul-Terraform-Sync API

When running in [daemon mode](/docs/nia/cli#daemon-mode), Consul-Terraform-Sync serves an HTTP API interface.

### Port

The API is served at the default port `8558` or a different port if set with [`port` configuration](/docs/nia/configuration#port)

### Version Prefix

All API routes are prefixed with `/v1/`. This documentation is for v1 of the API, which is the only version currently.

Example: `localhost:8558/v1/status`

### Error

Successful API requests will receive a 2XX success status code. For other unsuccessful status codes, when possible, more details will be provided in a response body. The response will be a JSON map with an "error" key.

Example: Status 400 Bad Request
```json
{
  "error": "example error message: unsupported status parameter value"
}
```

## Status

The `/status` endpoints share status-related information for tasks. This information is available for understanding the status of individual tasks and across tasks.

The health status value is determined by aggregating the success or failure of the event of a task detecting changes in Consul services and then updating network infrastructure. Currently, only the 5 most recent events are stored in Consul-Terraform-Sync. For more information on the hierarchy of status information and how it is collected, see [Status Information](/docs/nia/tasks#status-information).

### Overall Status

This endpoint currently returns the overall status information for all tasks.

| Method | Path                | Produces           |
| ------ | ------------------- | ------------------ |
| `GET`  | `/status` | `application/json` |

#### Request Parameters
Currently no request parameters are offered for the overall status API.

#### Response Fields

* `task_summary` - Summary of the count of tasks for each health status. See [Task Status API](/docs/nia/api#task-status) to learn more about how health status is determined.
  * `successful` - (int) The number of tasks that have a 'successful' health status
  * `errored` - (int) The number of tasks that have a 'errored' health status
  * `critical` - (int) The number of tasks that have a 'critical' health status


#### Example

Request:
```shell-session
$ curl localhost:8558/v1/status
```

Response:
```json
{
  "task_summary": {
    "successful": 28,
    "errored": 5,
    "critical": 1
  }
}
```

### Task Status

This endpoint returns the individual task status information for a single specified task or for all tasks.

Task health status value is determined by the success or failure of all stored [event data](/docs/nia/tasks#event) on the process of updating network infrastructure for a task. Currently only the 5 most recent events are stored per task.
 - Successful: The most recent stored event is successful.
 - Errored: The most recent stored event is not successful but all previous stored events are successful.
 - Critical: The most recent stored event is not successful and one or more previous stored events are also not successful.
 - Unknown: No event data is stored for the task.

| Method | Path                | Produces           |
| ------ | ------------------- | ------------------ |
| `GET`  | `/status/tasks/:task` | `application/json` |

#### Request Parameters

* `task` - (string) Option to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.
* `include` - (string) Only accepts the value "events". Use to include stored event information in response.
* `status` - (string) Only accepts health status values "successful", "errored", "critical", or "unknown". Use to filter response by tasks that have the specified health status value. Recommend setting this parameter when requesting all tasks i.e. no `task` parameter is set.

#### Response Fields

The response is a JSON map of task name to a status information structure with the following fields.

* `task_name` - (string) Name that task is configured with in Consul-Terraform-Sync.
* `status` - (string) Values are "successful", "errored", "critical", or "unknown". This is determined by the success or failure of all stored events on the network infrastructure update process for the task, as described earlier.
* `services` - (list[string]) List of the services configured for the task.
* `providers` - (list[string]) List of the providers configured for the task.
* `events_url` - (string) Relative URL to retrieve the event data stored for the task.
* `events` - [(list[Event])](/docs/nia/api#event) - List of stored events that inform the task's status. See section below for information on event data. This field is only included in the response upon request by setting the `?include=events` parameter. The relative URL for the request to include events can be retrieved from the `events_url` field.

##### Event

Event represents the process of updating network infrastructure of a task. The data is captured in a JSON structure. For more details on the scope of an event, see [Event](/docs/nia/tasks#event).

* `id` - (string) UUID to uniquely identify the event.
* `success` - (bool) Indication of whether the event was successful or not.
* `start_time` - (time) Time when the event started.
* `end_time` - (time) Time when the event ended.
* `task_name` - (string) Name that task is configured with in Consul-Terraform-Sync.
* `error` Information when the event fails. Null when successful.
  * `message` - (string) Error message that is returned on failure.
* `config`
  * `services` - (list[string]) List of the services configured for the task.
  * `source` - (string) Source configured for the task.
  * `providers` - (list[string]) List of the providers configured for the task.

#### Example: All Task Statuses

Request:
```shell-session
$ curl localhost:8558/v1/status/tasks
```

Response:
```json
{
  "task_a": {
    "task_name": "task_a",
    "status": "successful",
    "providers": [
      "local"
    ],
    "services": [
      "api"
    ],
    "events_url": "/v1/status/tasks/task_a?include=events"
  },
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "providers": [
      "null"
    ],
    "services": [
      "web"
    ],
    "events_url": "/v1/status/tasks/task_b?include=events"
  }
}
```

#### Example: Individual Task Status with Events

Request:
```shell-session
$ curl localhost:8558/v1/status/tasks/task_b?include=events
```

Response:
```json
{
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "providers": [
      "null"
    ],
    "services": [
      "web",
    ],
    "events_url": "/v1/status/tasks/task_b?include=events",
    "events": [
      {
        "id": "44137ba2-8fc9-6cbe-0e0e-e9305ee4f7f9",
        "success": false,
        "start_time": "2020-11-24T12:06:51.858292-05:00",
        "end_time": "2020-11-24T12:06:52.770165-05:00",
        "task_name": "task_b",
        "error": {
          "message": "example error: terraform-apply error"
        },
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web",
          ],
          "source": "../modules/test_task"
        }
      },
      {
        "id": "ef202675-502f-431f-b133-ed64d15b0e0e",
        "success": true,
        "start_time": "2020-11-24T12:04:18.651231-05:00",
        "end_time": "2020-11-24T12:04:20.900115-05:00",
        "task_name": "task_b",
        "error": null,
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web",
          ],
          "source": "../modules/test_task"
        }
      }
    ]
  }
}
```