> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bronto.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bronto Ingestion Endpoints

> Reference for Bronto's ingestion endpoints, including supported formats, OTLP and HTTP routes, regional URLs, authentication, and when to use each.

## Overview

Bronto exposes two distinct endpoint types. Using the wrong one is the most common cause of `400` errors — confirm which applies to your agent before configuring.

<Info>
  We recommend routing logs, metrics, and traces through the OpenTelemetry Collector rather than sending HTTP requests directly. The Collector handles batching, compression, and retries on failure. Log forwarders such as Fluent Bit, Logstash, and Vector remain a good choice for log-only sources. Direct HTTP is supported for cases where running an agent isn't practical.
</Info>

| Endpoint                                                                  | Accepts                                          | Typical agents                                           |
| ------------------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| `ingestion.eu.bronto.io` / `ingestion.us.bronto.io`                       | Any format — JSON, syslog, logfmt, CEF, raw text | Fluent Bit, Logstash, FireLens, EventBridge, custom HTTP |
| `ingestion.eu.bronto.io/v1/logs` / `ingestion.us.bronto.io/v1/logs`       | OTLP protobuf or OTLP/JSON                       | OpenTelemetry Collector                                  |
| `ingestion.eu.bronto.io/v1/metrics` / `ingestion.us.bronto.io/v1/metrics` | OTLP protobuf or OTLP/JSON                       | OpenTelemetry Collector                                  |
| `ingestion.eu.bronto.io/v1/traces` / `ingestion.us.bronto.io/v1/traces`   | OTLP protobuf or OTLP/JSON                       | OpenTelemetry Collector                                  |

## Authentication

All endpoints accept the Bronto API key header:

```
x-bronto-api-key: <YOUR_API_KEY>
```

The base ingestion endpoint also supports HTTP Basic authentication for products that provide a fixed authentication menu instead of custom headers:

| Field    | Value                                       |
| -------- | ------------------------------------------- |
| Username | Any non-empty value, such as `bronto`       |
| Password | Your Bronto API key with the Ingestion role |

```bash Basic authentication theme={"dark"}
curl -u "bronto:<YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  --data-binary '{"message":"authenticated with HTTP Basic"}' \
  "https://ingestion.<REGION>.bronto.io/?service_namespace=<COLLECTION>&service_name=<DATASET>"
```

The username is ignored; the API key must be the password. Basic authentication applies to the base endpoint used for logs. Continue to use the `x-bronto-api-key` header for OTLP logs, metrics, and traces.

See [API Keys](/Account-Management/API-Keys) for how to generate a key.

***

## Base Endpoint

The base endpoint (no path) accepts any payload format and performs no schema validation. It is the right choice for any agent that sends JSON, plain text, or structured log lines over HTTP.

### Automatically parsed formats

For the following formats, Bronto detects and extracts fields automatically — no configuration required.

| Format                                      | Fields extracted                                                                                                                      |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Structured JSON** (Logrus, Winston, etc.) | All top-level key-value fields                                                                                                        |
| **Nested JSON**                             | Nested objects flattened to dot notation — e.g. `context.user`, `context.request_id`                                                  |
| **RFC 5424 Syslog**                         | `pri`, `facility`, `severity`, `hostname`, `appname`, `procid`, `msgid`, `timestamp`, `version`                                       |
| **Logfmt**                                  | All key=value pairs — e.g. `level`, `msg`, `user`, `duration`. Also parsed when logfmt appears as the value of a JSON `message` field |
| **GELF**                                    | `version`, `host`, `short_message`, `level`, and underscore-prefixed custom fields                                                    |
| **Log4j2 JSON**                             | `level`, `loggerName`, `message`, `thread`, `instant.epochSecond`, `instant.nanoOfSecond`, nested `thrown` fields                     |
| **CEF**                                     | CEF version and extension key-value pairs — e.g. `src`, `dst`, `suser`                                                                |

### Formats stored verbatim

Other formats — RFC 3164 BSD syslog, Apache Common Log, Docker JSON, raw text — are accepted and stored as-is. Most log forwarders and the OpenTelemetry Collector can parse or transform these into structured fields before sending. If you are sending data directly, use the [custom parser](/core-features/custom-parser) to define extraction rules.

***

## OTLP Endpoints

The `/v1/logs`, `/v1/metrics`, and `/v1/traces` endpoints accept OTLP over HTTPS on port `443` in **both protobuf and JSON encoding**. The OpenTelemetry Collector handles OTLP serialisation, batching, and retry automatically.

| Signal  | EU                                          | US                                          |
| ------- | ------------------------------------------- | ------------------------------------------- |
| Logs    | `https://ingestion.eu.bronto.io/v1/logs`    | `https://ingestion.us.bronto.io/v1/logs`    |
| Metrics | `https://ingestion.eu.bronto.io/v1/metrics` | `https://ingestion.us.bronto.io/v1/metrics` |
| Traces  | `https://ingestion.eu.bronto.io/v1/traces`  | `https://ingestion.us.bronto.io/v1/traces`  |

### Encodings

Set `Content-Type` to match the encoding you send. Protobuf remains the default for the Collector and the OTel SDKs, and is the more compact option on the wire.

| Encoding      | `Content-Type`           |
| ------------- | ------------------------ |
| OTLP protobuf | `application/x-protobuf` |
| OTLP/JSON     | `application/json`       |

OTLP/JSON is useful when a client cannot produce protobuf — a script, a serverless function, or a platform that only emits JSON over HTTP. The body must be a single JSON object matching the OTLP request schema for that signal (for example `ExportLogsServiceRequest` for `/v1/logs`), not NDJSON.

```bash OTLP/JSON logs theme={"dark"}
curl -X POST https://ingestion.eu.bronto.io/v1/logs \
  -H "x-bronto-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "<DATASET>"}},
          {"key": "service.namespace", "value": {"stringValue": "<COLLECTION>"}}
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "1705314600000000000",
          "severityText": "INFO",
          "body": {"stringValue": "user login successful"}
        }]
      }]
    }]
  }'
```

To send OTLP/JSON from an OpenTelemetry Collector, set `encoding: json` on the `otlphttp` exporter:

```yaml otel-config.yaml theme={"dark"}
exporters:
  otlphttp:
    endpoint: https://ingestion.eu.bronto.io
    encoding: json
    headers:
      x-bronto-api-key: <YOUR_API_KEY>
```

OTel SDKs select the encoding through the exporter protocol — `http/protobuf` or `http/json`, set with `OTEL_EXPORTER_OTLP_PROTOCOL`. Not every language SDK implements `http/json`; check your SDK before switching.

<Note>
  Bronto supports OTLP sums, gauges, summaries, and explicit histograms. Exponential histograms are not currently supported, and the Metric Explorer does not currently provide a Rate function.
</Note>

<Warning>
  Trace data must go to `/v1/traces`. Sending traces to the base endpoint stores them as log events — trace correlation and the traces UI will not work.
</Warning>

***

## Direct HTTP Custom Ingestion

If running a log forwarder or collector isn't practical, you can POST log events directly to the base endpoint from any HTTP client or script.

### Request format

All requests must be `POST` with a JSON Lines (NDJSON) body — one JSON object per line.

**Authentication**

Authenticate with either the `x-bronto-api-key` header or HTTP Basic authentication as described above. Do not send the API key in a URL query parameter.

**Required request header**

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

**Recommended headers**

These headers control how your data is organized in Bronto. See [Data Organization](/Search-and-Visualize/Partitions) for how datasets, collections, and tags work.

| Header                | Description                              |
| --------------------- | ---------------------------------------- |
| `x-bronto-dataset`    | Dataset to ingest into                   |
| `x-bronto-collection` | Collection name                          |
| `x-bronto-tags`       | Comma-separated tags to attach to events |

Products that support Basic authentication but cannot set routing headers can use `service_name` and `service_namespace` query parameters:

```text theme={"dark"}
https://ingestion.<REGION>.bronto.io/?service_namespace=<COLLECTION>&service_name=<DATASET>
```

These parameters override `x-bronto-dataset` and `x-bronto-collection` when both forms are present. Parameters named `header_x-bronto-*` are not supported.

**Other headers**

| Header             | Description                                      |
| ------------------ | ------------------------------------------------ |
| `Content-Encoding` | Compression format: `gzip`, `zstd`, or `deflate` |

**Event fields**

| Field       | Required    | Description                                      |
| ----------- | ----------- | ------------------------------------------------ |
| `message`   | Yes         | The log content string                           |
| `timestamp` | Recommended | ISO 8601 timestamp — e.g. `2024-01-15T10:30:00Z` |

### Examples

```bash Uncompressed theme={"dark"}
curl -X POST https://ingestion.eu.bronto.io \
  -H "x-bronto-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  --data-binary '{"timestamp":"2024-01-15T10:30:00Z","message":"user login successful","user":"alice"}
{"timestamp":"2024-01-15T10:30:01Z","message":"request completed","status":200}'
```

```bash gzip theme={"dark"}
echo '{"timestamp":"2024-01-15T10:30:00Z","message":"user login successful"}' | \
  gzip | \
  curl -X POST https://ingestion.eu.bronto.io \
    -H "x-bronto-api-key: <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -H "Content-Encoding: gzip" \
    --data-binary @-
```

```bash Zstandard theme={"dark"}
echo '{"timestamp":"2024-01-15T10:30:00Z","message":"user login successful"}' | \
  zstd | \
  curl -X POST https://ingestion.eu.bronto.io \
    -H "x-bronto-api-key: <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -H "Content-Encoding: zstd" \
    --data-binary @-
```

<Note>
  Zstandard offers the best compression ratio and is recommended for high-volume pipelines.
</Note>

### Batch processing

For large files, split into chunks and send each one:

```bash Batch ingest from file theme={"dark"}
#!/bin/bash
FILE="logs.ndjson"
BATCH_SIZE=5000
API_KEY="<YOUR_API_KEY>"
ENDPOINT="https://ingestion.eu.bronto.io"

split -l $BATCH_SIZE "$FILE" /tmp/batch_

for batch in /tmp/batch_*; do
  gzip -c "$batch" | curl -s -X POST "$ENDPOINT" \
    -H "x-bronto-api-key: $API_KEY" \
    -H "Content-Type: application/json" \
    -H "Content-Encoding: gzip" \
    --data-binary @-
  echo "Sent $batch"
done

rm /tmp/batch_*
```

### Compression ratios

Compressing payloads before sending reduces transfer size significantly. Typical ratios for CDN logs:

| Algorithm | `Content-Encoding` value | Typical ratio |
| --------- | ------------------------ | ------------- |
| gzip      | `gzip`                   | \~7.8%        |
| Zstandard | `zstd`                   | \~6.0%        |
| Deflate   | `deflate`                | \~7.8%        |

### Payload limits

| Payload type           | Maximum size           |
| ---------------------- | ---------------------- |
| Uncompressed           | 10 MB                  |
| Compressed (wire size) | 10 MB                  |
| Per line / entry       | 256 KB (262,144 bytes) |

Exceeding the payload size limits returns an HTTP `413`.

### Response codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `200` | Events ingested                   |
| `400` | Malformed request or invalid JSON |
| `401` | Invalid or missing API key        |
| `413` | Payload exceeds size limit        |
| `429` | Rate limit or quota exhausted     |

A `200` response means your data has been securely stored — no data will be lost. If the API returns an error, no data from that request is ingested.