> For the complete documentation index, see [llms.txt](https://docs.cloudtruth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudtruth.com/configuration-management/cli-and-api/rest-api.md).

# Rest API

Introduction to the CloudTruth API

## Introduction

Does CloudTruth have an API? Of course we do!

The CloudTruth API is the same API used by our SaaS offering. Anything that you can do in our GUI, you can do programmatically via the API.

## Overview

The CloudTruth API is a pretty standard RESTful-like HTTP API. You perform GET, PUT, POST, PATCH and DELETE operations models hosted by our web service. Operations require a JWT or [API Access Token](/org-management/access-control/access-tokens.md) in the Authorization header of the call. Parameters are passed to the web service via JSON in the body of the request. Results are returned as JSON structures in the body of the response.

Our complete REST API documentation is automatically generated and can be found here:

{% embed url="<https://api.cloudtruth.io/api/schema/redoc/#section/Authentication>" %}

We also provide an interactive web interface to the API:

{% embed url="<https://api.cloudtruth.io/api/schema/swagger/#/>" %}

## Getting Started

We will start you off with a basic example of a GET operation that will list your CloudTruth Environments. From the [environment\_list](https://api.cloudtruth.io/api/schema/redoc/#operation/environments_list) schema docs we can find the GET request query parameters and typical response.

## environments\_list

<mark style="color:blue;">`GET`</mark> `https://api.cloudtruth.io/api/v1/environments/`

Lists CloudTruth Environments

#### Query Parameters

| Name           | Type    | Description                                    |
| -------------- | ------- | ---------------------------------------------- |
| name           | string  |                                                |
| page           | integer | A page number within the paginated result set, |
| page\_size     | string  | Number of results to return per page.          |
| parent\_\_name | string  |                                                |

{% tabs %}
{% tab title="200 " %}

```
{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2021-07-19T19:22:44.689825Z",
            "description": "The auto-generated default environment.",
            "id": "ad34ea7d-c9cb-473e-93fb-06dc468cacd7",
            "modified_at": "2021-08-02T19:17:28.920832Z",
            "name": "default",
            "parent": null,
            "url": "https://api.cloudtruth.io/api/v1/environments/ad34ea7d-c9cb-473e-93fb-06dc468cacd7/"
        }
```

{% endtab %}
{% endtabs %}

Now you can issue a get request with your API Access token, here is a basic example in Python and Bash to get you going.

{% tabs %}
{% tab title="Python" %}

```python
import requests

token = "Your API Access token"
headers = {'Authorization': f'Api-Key {token}'}
url = "https://api.cloudtruth.io/api/v1/environments/"
response = requests.get(url, headers=headers)
environments = response.json()
print(json.dumps(environments, indent=4, sort_keys=True))
```

{% endtab %}

{% tab title="Bash" %}

```
token="Your API Access token"
curl -s --header "Content-Type: application/json" \
  --header "Authorization: Api-Key ${token}" \
  --request GET \
 https://api.cloudtruth.io/api/v1/environments/
```

{% endtab %}
{% endtabs %}

You can checkout out our repo for a few additional working examples.

{% embed url="<https://github.com/cloudtruth-demo/rest-api-examples>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cloudtruth.com/configuration-management/cli-and-api/rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.