# Connection and Configuration - Advanced Analytics API

We propose a REST API connection to the Advanced Analytics Data.

### REST API

The API is documented here: [OpenAPI](https://petstore.swagger.io/?url=https%3A%2F%2Fapi-datalake.ag5.io%2Fopenapi.json#/). Organizations will need an API token to get access to their data. This token can be requested via your Customer Success Manager. The API operations require bearer authentication (also called token authentication) which is an [HTTP authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) that involves security tokens called bearer tokens. 

Some of the parameters used in the API are explained here:

| Parameter          | Description                                                                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| organization\_name | <p>Can be retrieved from the url of your AG5 environment. </p><p><https://matrix.ag5.com/><strong>myorganization</strong>/main</p>                                                                                        |
| repository\_name   | <p>Can be retrieved from the url of your AG5 environment. </p><p><https://matrix.ag5.com/myorganization/><strong>main</strong></p>                                                                                        |
| page\_token        | Used for pagination. Is returned in the response header (key = x-ag5-pagetoken)                                                                                                                                           |
| page\_size         | Maximum number of records to return.                                                                                                                                                                                      |
| reference\_time    | For most events, this is treated as a ‘since’ and returns all records **after** this reference time. For EmploymentQualificationCompliance, only the events stored on the Day (Date) of the reference\_time are returned. |

The request header:

| Key             | Value                        |
| --------------- | ---------------------------- |
| Authorization   | Bearer \<the provided token> |
| Accept          | (optional) ‘text/csv’        |
| Accept-Encoding | (optional) ‘gzip’            |

The responses can be retrieved in JSON or CSV format. JSON is default, CSV can be obtained by including the Accept header.&#x20;

The API is again split up into Entities and Events. Note: the compliance calculations and the repository statistics can both be accessed via the Events endpoints.&#x20;

For Entities, we advise you to start with the request to retrieve the entity-types:

```
/organizations/{organization_name}/repositories/{repository_name}/ entity-types. 
```

These entity types are required as a parameter in many of the other requests. Don’t forget to use the full name in your request:

```
seaspray.v<number>.<EntityType> 
```

For Events, we advise you to start with the request to retrieve the event-types.

```
/organizations/{organization_name}/repositories/{repository_name}/ event-types. 
```

Each event has both a type and a subject. But only for SIEM events a type can have multiple subjects. To illustrate this, the Compliance event has only one type:&#x20;

```
seaspray.v1.GroupingCompliance
```

and one subject:&#x20;

```
compliance_computation
```

Therefore the events can be retrieved by only referring to the event\_type.&#x20;

The SIEM events have one type but can have different subjects. For Siem events it is therefore advised to use both the event\_type and event\_subject to retrieve the events.&#x20;

**reference\_time**

By default, the events that were created after 00:00 am today (European standard time) are returned. The parameter reference\_time can be used to specify the time in milliseconds since Jan 1, 1970 (Epoch or Unix timestamp) of the oldest event returned. &#x20;

*GroupingCompliance* calculations are performed during the night. This could be before or after midnight. This may mean that a request without reference\_time will return no events (because the last compliance calculation was done before 00:00 am today). Therefore we advise to use the reference\_time parameter and make sure you retrieve the events of the last 24 hours. &#x20;

For almost all Events, the events **after** the reference\_time are returned, except for *EmploymentQualificationCompliance* events, for which only the events of one day (the date of the reference\_time) are returned.

**page\_token**

The returned entities and events are usually split into different pages based on the page\_size. The page\_token, to request the next page is returned in the response header.&#x20;

> Note, this response header is not visible in the [OpenAPI](https://petstore.swagger.io/?url=https%3A%2F%2Fapi-datalake.ag5.io%2Fopenapi.json#/) - try it out functionality. If you use
>
> ```
> CURL --verbose 
> ```
>
> to call the endpoint in a terminal for example, the header will be visible.&#x20;

### <br>


---

# 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.ag5.com/data-management/advanced-analytics-api/connection-and-configuration-advanced-analytics-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.