# HTTP

If a device communicates over **HTTP** with akenza, an HTTP connector has to be setup and assigned to a data flow.

After creation, a secret is generated which has to be provided in the request. Both the secret and the device ID are set as query params in the HTTP request.

## Send an HTTP Uplink

<mark style="color:green;">`POST`</mark> `https://data-gateway.akenza.io/v3/capture?secret={uplinkSecret}&deviceId={deviceId}`

The body can be any **JSON** object.

#### Query Parameters

| Name                 | Type   | Description                                                                                                      |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| timestamp (optional) | string | The timestamp of the event (ISO-8601 formatted), defaults to the current time if not provided                    |
| topic (optional)     | string | The data topic ("default" will be used if not provided)                                                          |
| uplinkSecret         | string | The uplink secret used to authenticate the request (it is recommended to use the x-uplink-secret header instead) |
| deviceId             | string | The physical device ID                                                                                           |

#### Headers

| Name            | Type   | Description                                        |
| --------------- | ------ | -------------------------------------------------- |
| Content-Type    | string | application/json                                   |
| x-uplink-secret | string | The uplink secret used to authenticate the request |
| x-device-id     | string | The physical device ID                             |

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

```
{
    "id": "UUID",
    "timestamp": "ISO-8601 date string",
    "message": "uplink received"
}
```

{% endtab %}
{% endtabs %}

### Array Uplinks

The HTTP connectivity also supports the processing of array uplinks (not just a JSON property which is an array but the whole request body).

There are minimal differences when processing such an uplink in the script.&#x20;

{% hint style="info" %}
Refer to the [example event for array uplinks](/akenza.io/get-started/reference/scripting.md#example-array-uplink-event) in the Scripting section for more details.
{% endhint %}

### Support for using secret and device id in the header

Requests can be submitted by using secret and device id in the header. The header key should be `x-uplink-secret` and `x-device-id`. The value of the header is the secret of the device connector and the physical device id. Both values can be found on the **Device Detail Page** within *API-Configuration* or in the uplink URL.

### DeviceId Templating

The device id can be parsed from the request body using a JSON path by enabling the setting when creating an HTTP device connector.

* `$` The root element to query. This starts all path expressions.
* `$.<propertyName>` dot-notated property names

Examples:&#x20;

* `$.macAddress`&#x20;
* `$.sensorMessages[0].sensorId`

Note that always the first match is used from the body template: e.g. using a template like `$.sensorMessages[0].sensorId`, multiple messages in the same uplink by different devices are therefore not supported.&#x20;

### Plain HTTP endpoint

Use the endpoint `http://plain.data-gateway.akenza.io` if your device does not support HTTPS. We do not recommend to use this option as your data will be transmitted in plain text.


---

# 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.akenza.io/akenza.io/get-started/your-data-flow/device-connector/http.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.