# REST API

The **Green Stack REST API** allows you to extend your Green Stack account and integrate custom solutions.

The API is crafted around [REST](https://wikipedia.org/wiki/REST) and the REST architectural style to provide developers with a stateless and language-­agnostic interface. The API leverages common HTTP verbs and response codes, OAuth2 authentication, and resource­ oriented URLs.

## Accessing the API

The root API host is `https://api.greenstack.cloud/`

You must have an active subscription for the Green Stack REST API to add new API keys and make API calls. 

### Creating a new API key

To create a new API key:

1. **Login** to the **Green Stack Console** and navigate to **Settings**
2. Select **API Keys** from the sidebar
3. Select **New Key** to create a new API key
4. Provide a **Name** for the new key and **select** the desired **permissions**
5. Select **Save** to generate the key

Once you create a key, you must pass it with the `X-Green-Stack-Key` header to authenticate every request.

```
X-Green-Stack-Key: dgf...euhsdf
```

### API endpoint documentation

The API endpoints available are documented in an [Open API](https://spec.openapis.org/oas/latest.html) spec at [https://api.greensack.dev/v1](https://go.counterbalance.io/gs-api-ref)

## HATEOS

**HATEOAS (Hypermedia as the Engine of Application State)** is a constraint of the REST application architecture that lets us use hypermedia links in the API responses that allow the client to dynamically navigate resources without prior knowledge of the API.

Green Stack REST API returns HATEOS links in resource responses by default. These links outline relative access to related resources, collections, and references. 

### Toggling HATEOS links in API responses

Links may not be necessary or appropriate for every request. Links can be removed from the response by passing the `X-Green-Stack-Suppress-Links` header and setting it to `true`

```
X-Green-Stack-Suppress-Links: true
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.greenstack.dev/integration/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.