HTTP Source

Web apps can’t easily connect to a custom TCP port, so the HTTP source provides an alternative ingestion path with JSONL and binary support. This is what the JavaScript SDK uses.

[sources.http]
port = 8080

Endpoints

Method	Path	Content-Type	Description
POST	`/v1/events`	`application/json`	Ingest events (JSONL)
POST	`/v1/logs`	`application/json`	Ingest logs (JSONL)
POST	`/v1/ingest`	`application/x-flatbuffers`	Binary FlatBuffer batches
GET	`/health`	—	Returns `{"status": "ok"}`

The JSONL endpoints accept one JSON object per line. The binary endpoint accepts pre-encoded FlatBuffer batches — the same wire format the TCP source uses. Content types application/octet-stream and application/x-tell are also accepted on the binary endpoint.

Authentication

Three ways to authenticate, in precedence order:

Authorization: Bearer <key> header
X-API-Key: <key> header
?token=<key> query parameter

The query parameter option exists for browser SDKs that need to avoid CORS preflight requests on simple POST requests.

curl -X POST https://tell.example.com/v1/events \
  -H "Authorization: Bearer a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{"type":"track","event":"page_view","device_id":"abc123"}'

Keys are 32 hex characters. See API keys for creating and managing them.

Responses

202 Accepted — all items ingested successfully:

{"accepted": 12, "request_id": "req_a1b2c3"}

207 Multi-Status — partial success (some items rejected):

{
  "accepted": 10,
  "rejected": 2,
  "errors": [
    {"line": 3, "error": "missing required field: device_id"},
    {"line": 7, "error": "invalid event type"}
  ],
  "request_id": "req_a1b2c3"
}

400 Bad Request — all items rejected or invalid format. 401 Unauthorized — missing or invalid API key. 413 Payload Too Large — request body exceeds max_payload_size. 429 Too Many Requests — rate limited after repeated auth failures. 503 Service Unavailable — pipeline backpressure (channel full).

CORS and browser clients

CORS is enabled by default so browser SDKs work without extra setup. The source mirrors the request’s Origin header and allows Authorization, Content-Type, X-API-Key, and X-Workspace-ID headers. To restrict allowed origins:

[sources.http]
port = 8080
cors_origins = ["https://myapp.com", "https://staging.myapp.com"]

TLS

Tell supports HTTPS natively via rustls. Provide PEM-encoded certificate and key files:

[sources.http]
port = 443
tls_cert_path = "/etc/tell/cert.pem"
tls_key_path = "/etc/tell/key.pem"

When both paths are set, the source binds as HTTPS. Omit them to run plain HTTP (the default). For production, you can also terminate TLS at a reverse proxy like Caddy instead — see Reverse proxy below.

Reverse proxy

Running Caddy in front of Tell is the simplest way to get automatic HTTPS with Let’s Encrypt certificates and zero TLS configuration:

tell.example.com {
    reverse_proxy localhost:8080
}

Caddy handles certificate provisioning, renewal, and TLS termination automatically. Enable trust_proxy in Tell so the real client IP is captured from X-Forwarded-For:

[sources.http]
port = 8080
trust_proxy = true

This also works with nginx or any reverse proxy that sets X-Forwarded-For. Only enable trust_proxy when the HTTP source is behind a trusted proxy — clients can forge the header otherwise.

Rate limiting

Authentication failures are rate-limited per IP. After 10 failures within 60 seconds, the IP is temporarily blocked with 429 Too Many Requests. The rate limiter cleans up expired entries every 5 minutes.

Safety limits

JSONL endpoints enforce two limits to prevent denial-of-service:

10,000 lines per request — requests with more lines are rejected
32 levels of JSON nesting — deeply nested objects are rejected before parsing

These limits are not configurable. Malformed JSON lines are skipped individually — a single bad line won’t reject the entire request (you’ll get a 207 response with per-line errors).

Configuration reference

[sources.http]
port = 8080
address = "::"              # Bind address (dual-stack IPv4+IPv6)
max_payload_size = 16777216  # Max request body in bytes (16 MB)
batch_size = 500             # Items per internal batch
flush_interval = "100ms"     # Flush partial batches after this interval
request_timeout = "30s"      # HTTP request timeout
cors_enabled = true          # Enable CORS headers
cors_origins = []            # Allowed origins (empty = all)
request_logging = false      # Log every HTTP request
trust_proxy = false          # Trust X-Forwarded-For header
tls_cert_path = ""           # PEM certificate path (enables HTTPS)
tls_key_path = ""            # PEM private key path (enables HTTPS)

What’s next

TCP source — higher throughput for native SDKs
JavaScript SDK — the primary client for the HTTP source
API keys — create and manage streaming keys
Routing — control where HTTP data goes after ingestion

Getting Started

Tracking

Pipeline

Analytics

Installing

HTTP Source

Endpoints

Authentication

Responses

CORS and browser clients

TLS

Reverse proxy

Rate limiting

Safety limits

Configuration reference

What’s next

​Endpoints

​Authentication

​Responses

​CORS and browser clients

​TLS

​Reverse proxy

​Rate limiting

​Safety limits

​Configuration reference

​What’s next

Endpoints

Authentication

Responses

CORS and browser clients

TLS

Reverse proxy

Rate limiting

Safety limits

Configuration reference

What’s next