# Create a Monitoring Pipeline Instance

* Creates a new Pipeline.
* The full Pipeline needs to be provided to create the object. Optional data will be filled with defaults or left empty.
* To ensure that the Pipeline with the provided ID is created or modified, perform `PUT` request.

## Pipeline authentication for secure metric ingestion

To ensure secure and authorized metric data submission, each Monitoring Pipeline is assigned a unique `key` upon creation. This key acts as a credential for metric exporters or agents pushing data to the pipeline's HTTP endpoint.

{% hint style="warning" %}
For security reasons, the API key is not returned in the response after creating a pipeline. It's crucial to store the key securely during pipeline creation for future reference.
{% endhint %}

**Key points**

* The `key` is included in the `metadata` section of the pipeline response (see `"key": "momSrlgAAEmaYEvBsMr^HsYn"` in the example).
* Metric exporters or agents must be configured to include this key in their requests to the pipeline's HTTP endpoint for successful data ingestion.
* This mechanism safeguards the pipeline from unauthorized data submissions and maintains data integrity within the Monitoring Service.

**Best practices**

* Store the pipeline key securely for authorized metric sources only.
* Avoid sharing or exposing the key publicly.
* Consider [<mark style="color:blue;">**rotating pipeline keys**</mark>](https://docs.ionos.com/cloud/~/revisions/AMiYziCllTKB2y2lmONY/observability/monitoring-service/api-how-tos/obtain-key) periodically for enhanced security.

To create a Monitoring Pipeline, perform a `POST` request.

## Request

```bash
curl --location \
--request POST 'https://monitoring.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
  "metadata": {},
  "properties": {
    "name": "Pipeline1"
  }
}'
```

{% tabs %}
{% tab title="Request Body Parameters" %}
Below is the list of mandatory body parameters for creating a Pipeline:

| Body Parameters   | Required | Type   | Description                                                                                    | Example                   |
| ----------------- | -------- | ------ | ---------------------------------------------------------------------------------------------- | ------------------------- |
| `metadata`        | no       | object | Metadata                                                                                       | `{}`                      |
| `properties`      | yes      | object | A pipeline consists of the generic rules and configurations of a monitoring pipeline instance. | `{ "name": "Pipeline1" }` |
| `properties.name` | yes      | string | Name of your Pipeline.                                                                         | `Pipeline1`               |
| {% endtab %}      |          |        |                                                                                                |                           |

{% tab title="Request Header Parameters" %}
To make authenticated requests to the API, the following fields are mandatory in the request header:

| Header Parameters | Required | Type   | Description                                                                                                                              |
| ----------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`   | yes      | string | The Bearer token enables requests to authenticate using a JSON Web Token (JWT). The token can be generated using the Authentication API. |
| `Content-Type`    | yes      | string | Set this to `application/json`.                                                                                                          |
| {% endtab %}      |          |        |                                                                                                                                          |
| {% endtabs %}     |          |        |                                                                                                                                          |

## Response

The following is a sample response. The values returned by each response differ based on the request.

```json
{
  "id": "f72521ba-1590-5998-bf96-6eb997a5887d",
  "type": "pipeline",
  "href": "/pipelines/f72521ba-1590-5998-bf96-6eb997a5887d",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "key": "momSrlgAAEmaYEvBsMr^HsYn",
    "grafanaEndpoint": "https://grafana.jf9ejf8t6hrt.logging.de-txl.ionos.com",
    "httpEndpoint": "https://f8ss7fgr7s-metrics.jf9ejf8t6hrt.monitoring.de-txl.ionos.com"
  },
  "properties": {
    "name": "Pipeline1"
  }
}
```

{% hint style="success" %}
**Result:** A Monitoring Pipeline is successfully created.
{% endhint %}