# HTTP

Accepts POSTed data directly to the Monad API endpoint.

## Requirements

There are no Prerequisites to start using the HTTP input.  Simply create an HTTP Input and attach it to a pipeline.

## Details

The HTTP input is an extremely flexible method for ingesting data into the Monad platform.  By creating an Http input, users can publish any data they wish to a pipeline without needing to have a specifically implemented input to support that data.  This allows data to be sent via any programming language or even via curl as a starting point.

## Sending data

Sending data to an Http input requires sending a POST request to the Monad API with the pipeline id  with `/api/v2/http/send/{pipeline_id}` and a valid request body.

The request body accepts either:
- A single JSON object
- Multiple JSON objects in JSONL (JSON Lines) format - line-delimited JSON where each line is a separate JSON object

Each JSON object will be sent to the stream exactly as it is provided.

## Authentication

All requests to the HTTP input endpoint require authentication using an organization API key with the `pipeline:data:write` permission.

### API Key Requirements

The API key must meet the following requirements:

- Must be an **organization API key** (not a personal API key)
- Must have the `pipeline:data:write` permission, which is included by default in the following roles:
  - **Contributor**
  - **System Administrator**
- Alternatively, the permission can be added to a custom role

### Required Headers

You must include one of the following authentication headers:

- **Authorization**: `ApiKey <API_KEY>`
- **x-api-key**: `<API_KEY>`

The `Content-Type` header is not required, but if provided, it must be set to `application/json`.

## Examples

### cURL Example

```bash
curl --request POST \
  --url https://app.monad.com/api/v2/http/send/<pipeline-id> \
  --header 'authorization: ApiKey <api-key>' \
  --data '
    {
      "event_type": "authentication",
      "user": "admin@example.com",
      "status": "success",
      "timestamp": "2024-01-15T10:30:00Z"
    }{
      "event_type": "file_access",
      "user": "user@example.com",
      "file_path": "/sensitive/data.txt",
      "timestamp": "2024-01-15T10:31:00Z"
    }'
```

### Python Example

```python
import requests
import json

url = 'https://app.monad.com/api/v2/http/send/{pipeline_id}'
headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'ApiKey <API_KEY>',
}

# Line-delimited JSON records
data = '''{
  "event_type": "authentication",
  "user": "admin@example.com",
  "status": "success",
  "timestamp": "2024-01-15T10:30:00Z"
}{
  "event_type": "file_access",
  "user": "user@example.com",
  "file_path": "/sensitive/data.txt",
  "timestamp": "2024-01-15T10:31:00Z"
}'''

response = requests.post(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=2))
```

## Response Examples

### Success Response (200)

```json
{
  "status": "success",
  "count": 1
}
```

### Error Responses

| Response | Description |
|----------|-------------|
| `authorization required` | No authentication header was provided |
| `invalid JWT` | The provided JWT token is invalid |
| `failed to get api key` | The API key is no longer valid |
| `access denied: this endpoint requires pipeline:data:write` | The API key lacks the required `pipeline:data:write` permission |
| `error reading request body` | The request body contains invalid JSON |
| `An item of this type does not exist.` | The provided pipeline ID does not exist |
| `pipeline not found or not an HTTP input` | The pipeline exists but is not configured as an HTTP input |