# Developer notes

## API Root

The API provides a set of resources that can be accessed via a `root URL`, which will be provided to you by VEASYBL along with the `API KEY` for authenticating your calls.

```bash
https://[retailer-endpoint]/v1/
```

`[retailer-endpoint]` is the API host.

`v1` indicates that you want to use the first version of the API. If you attempt to request another version of the API, you will receive a 404 error, as there is currently only one version of the API.

## Available HTTP methods

| Method | Description                                       |
| ------ | ------------------------------------------------- |
| GET    | Retrieves a resource or a collection of resources |
| POST   | Create a new resource                             |

## Content-type

JSON is the format supported by the API. You will need to explicitly tell the API that you are providing JSON content using a `Content-type` header set to `application/json`.

```bash
curl -X POST [retailer-endpoint]/v1/_event \
-H "Content-Type: application/json" \
-H "x-api-key: [your_api_key_goes_here]" \
-d '{ "visitor": "9e3b1e38-7d65-4b07-a245-f9262d2bcad6" }'
```

## Authentication :unlock: 

For security reasons, you will need to be authenticated to access the API. To authenticate your calls, **veasybl** will provide an API KEY. This key must be present in the `x-api-key` header

```bash
curl https://[retailer-endpoint]/v1/health \
-H "x-api-key: [your_api_key_goes_here]" \
-H "Content-Type: application/json" \
```

## HTTP status

Here are all the answers you can get when making API requests.

### Success 

#### 200 SUCCESS 

Getting a resource or a collection of resources gives a response `200 OK`.

```bash
HTTP/1.1 200 OK
```

###  Errors 

There are several possible types of errors when requesting through the API.

#### 400 ERROR 

Sending malformed data causes a response `400 Bad Request`.

```json
HTTP/1.1 400 Bad Request
```

#### 401 ERROR

Attempting to access the API without authentication results in a response `401 Unauthorized.`

```bash
HTTP/1.1 401 Unauthorized
```

#### 403 ERROR

Trying to access the API without authorization results in a response  `403 Forbidden`.

```bash
HTTP/1.1 403 Forbidden
```

#### 404 ERROR

Attempting to access a non-existent resource results in a response  `404 Not Found.`

```bash
HTTP/1.1 404 Not Found
```


---

# 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.veasybl.io/en/api-integration/developer-notes.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.