# API Reference

The API is a HTTP RESTful API based around resource oriented URLs. It uses standard HTTP verbs and returns JSON on all requests where a data response is expected.

The API is served over TLS (HTTPS) to ensure data privacy, unencrypted HTTP is not supported—or rather will result in a redirect to HTTPS.

## Authorization <a href="#authorization" id="authorization"></a>

To use the API an API key is needed. API keys can be generated in the platform and are coupled to the organization under which it is created. It is possible to have API keys with more or less access. This can be done so through Tags.

{% embed url="<https://help.onomondo.com/en/articles/141625-how-to-setup-an-api-key>" %}

{% embed url="<https://help.onomondo.com/en/articles/152946-how-to-set-up-user-access-control-using-tags>" %}

Once you have generated your API key, you need to add it into the header of all HTTP requests made. We utilize the `Authorization` header for this purpose, e.g.:

```
Authorization: <YOUR_API_KEY>
```

## Rate limiting <a href="#rate-limiting" id="rate-limiting"></a>

Every minute a user can send 600 API calls to our server, averaging to one every 0.1 seconds. You can monitor the API limits in the response headers.

* `x-ratelimit-limit` is a number that informs you of the maximum amount of calls that can be made per period in total.
* `x-ratelimit-remaining` is a number that informs you of how many calls you have left in the current period.
* `x-ratelimit-reset` is an epoch/Unix timestamp informing you of when the period will be reset, i.e. at this point in time `x-ratelimit-remaining` will be reset.

```
x-ratelimit-limit: 600
x-ratelimit-remaining: 520
x-ratelimit-reset: 1730239201
```

Which would indicate that at this point in time you have 520 calls left in the given period and that they will be reset at `1730239201` (Tuesday, October 29, 2024 11:00:01 PM [GMT+01:00](https://www.epochconverter.com/timezones?q=1730239201)), meaning that in the current period 600 - 520 = 80 calls were already made.

## Response limits <a href="#response-limits" id="response-limits"></a>

Each response can return a maximum of 1000 objects and the default limit can vary per endpoint. If more objects for a given endpoint is required then consult the pagination method of said endpoint.


---

# 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.onomondo.com/readme.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.