Ingester API Reference

The Kloudfuse ingester exposes HTTP endpoints for all major telemetry formats. You can send data directly from any client that supports OTLP, Prometheus remote write, Datadog-compatible agents, FluentBit, Fluentd, or Filebeat — without deploying an additional collector or agent.

Overview

All ingester endpoints are reachable at your cluster’s external hostname:

https://<kloudfuse-hostname>/ingester/<endpoint-path>

The ingester accepts compressed payloads via the Content-Encoding header. Supported compression formats: gzip, deflate, zstd. Prometheus remote write additionally requires snappy.

Authentication

If ingestion authentication is enabled on your cluster, include an API key on every request. The header name depends on the endpoint family:

To generate an API key, see Ingestion Authentication with API Key.

OTLP (OpenTelemetry Protocol)

The ingester implements the full OTLP HTTP specification. Use these endpoints with any OpenTelemetry Collector, SDK, or instrumented application.

Example: Send a Metric via OTLP/HTTP JSON

curl -X POST https://<kloudfuse-hostname>/ingester/otlp/metrics \
  -H "Content-Type: application/json" \
  -H "Kf-Api-Key: <token>" \
  -d '{\
    "resourceMetrics": [{\
      "resource": {\
        "attributes": [\
          {"key": "host.name", "value": {"stringValue": "prod-server-1"}},\
          {"key": "service.name", "value": {"stringValue": "my-app"}}\
        ]\
      },\
      "scopeMetrics": [{\
        "metrics": [{\
          "name": "app.request.count",\
          "description": "Total HTTP requests",\
          "unit": "1",\
          "sum": {\
            "dataPoints": [{\
              "asInt": "1042",\
              "timeUnixNano": "1700000000000000000",\
              "attributes": [\
                {"key": "http.method", "value": {"stringValue": "GET"}}\
              ]\
            }],\
            "aggregationTemporality": 2,\
            "isMonotonic": true\
          }\
        }]\
      }]\
    }]
  }'

Example: Send a Log Record via OTLP/HTTP JSON

curl -X POST https://<kloudfuse-hostname>/ingester/otlp/v1/logs \
  -H "Content-Type: application/json" \
  -H "Kf-Api-Key: <token>" \
  -d '{\
    "resourceLogs": [{\
      "resource": {\
        "attributes": [\
          {"key": "service.name", "value": {"stringValue": "my-app"}}\
        ]\
      },\
      "scopeLogs": [{\
        "logRecords": [{\
          "timeUnixNano": "1700000000000000000",\
          "severityText": "ERROR",\
          "body": {"stringValue": "Database connection refused"},\
          "attributes": [\
            {"key": "env", "value": {"stringValue": "production"}}\
          ]\
        }]\
      }]\
    }]
  }'

OpenTelemetry Collector Configuration

To export from an OTel Collector to Kloudfuse, configure the otlphttp exporter:

exporters:
  otlphttp:
    metrics_endpoint: https://<kloudfuse-hostname>/ingester/otlp/metrics
    logs_endpoint: https://<kloudfuse-hostname>/ingester/otlp/v1/logs
    traces_endpoint: https://<kloudfuse-hostname>/ingester/otlp/traces
    headers:
      Kf-Api-Key: <token>

Prometheus Remote Write

The ingester implements the Prometheus remote write protocol. Any Prometheus instance or compatible agent (Grafana Agent, VictoriaMetrics agent, etc.) can write directly to Kloudfuse.

Payload must be a snappy-compressed Prometheus WriteRequest protobuf. The Content-Encoding: snappy header is required.

Prometheus Configuration

Add a remote_write block to your prometheus.yml:

remote_write:
  - url: https://<kloudfuse-hostname>/ingester/write
    authorization:
      credentials: <token>
    queue_config:
      max_samples_per_send: 10000
      batch_send_deadline: 5s

Grafana Agent / Alloy Configuration

prometheus.remote_write "kloudfuse" {
  endpoint {
    url = "https://<kloudfuse-hostname>/ingester/write"
    bearer_token = "<token>"
  }
}

Datadog-Compatible Endpoints

The ingester accepts data from the Datadog Agent and any Datadog-compatible client. Use Dd-Api-Key for authentication.

Example: Send Logs (Datadog JSON Format)

curl -X POST https://<kloudfuse-hostname>/ingester/api/v2/logs \
  -H "Content-Type: application/json" \
  -H "Dd-Api-Key: <token>" \
  -d '[{\
    "hostname": "web-01",\
    "service": "my-app",\
    "status": "error",\
    "message": "Unhandled exception in request handler",\
    "ddtags": "env:production,version:2.1.0"\
  }]'

FluentBit

Point a FluentBit output at the Kloudfuse ingester using the HTTP output plugin.

FluentBit Output Configuration

[OUTPUT]
    Name              http
    Match             *
    Host              <kloudfuse-hostname>
    Port              443
    TLS               On
    URI               /ingester/v1/fluent_bit
    Format            json
    Header            Kf-Api-Key <token>
    Compress          gzip

Fluentd

Point a Fluentd output at the Kloudfuse ingester using the HTTP output plugin.

Fluentd Output Configuration

<match **>
  @type http
  endpoint https://<kloudfuse-hostname>/ingester/v1/fluentd
  headers {"Kf-Api-Key": "<token>"}
  content_type application/x-ndjson
  <format>
    @type json
  </format>
  <buffer>
    flush_interval 5s
  </buffer>
</match>

Filebeat

Configure Filebeat to ship logs using the Elasticsearch output pointed at the Kloudfuse ingester, which exposes an Elasticsearch-compatible bulk ingestion endpoint.

Filebeat Output Configuration

output.elasticsearch:
  hosts: ["https://<kloudfuse-hostname>/ingester/api/v1/filebeat"]
  api_key: "ignored:<token>"   # value after ":" is sent as Kf-Api-Key
  ssl.verification_mode: full

Events

The ingester accepts raw event payloads from webhook sources.

Response Codes

Compression Reference

All endpoints support compressed request bodies via the Content-Encoding header: