Ingest API

Every signal reaches Maple through one OTLP/HTTP gateway. Any OpenTelemetry SDK or Collector that can export OTLP over HTTP works without a Maple-specific exporter.

Endpoints

Use the ingest host of your organization’s region. A key from one region is rejected by the other. A standard exporter appends the signal path itself:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer maple_pk_…"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Authentication

Send your ingest key on every request, either as a Bearer token or in the x-maple-ingest-key header. The Bearer prefix is case-insensitive.

Authorization: Bearer maple_pk_…
x-maple-ingest-key: maple_pk_…

Ingest keys can only send data, and each belongs to one organization. Use the public key (maple_pk_…) in browsers and mobile apps, where it ships to end users, and the private key (maple_sk_…) on servers. Find both under Settings → Ingestion in the dashboard. Authentication explains the difference.

The literal key MAPLE_TEST is accepted and returns 200, but the data is discarded. Use it in CI or example code where you want the exporter to run without sending anything.

Content types and compression

For compression, send Content-Encoding: gzip. Omit the header (or send identity) for an uncompressed body. gzip is the only compression supported. zstd, deflate and br are rejected with 415, so set your exporter’s compression to gzip or none.

Browsers

The gateway answers CORS preflights from any origin, so a browser can export directly. Allowed request headers are Authorization, Content-Type, Content-Encoding, x-maple-ingest-key and the x-maple-* headers the browser SDK sends. No response headers are exposed to scripts, so browser code cannot read Retry-After; back off on a fixed schedule instead.

Status codes

Errors carry a JSON body with the same envelope as the Maple API:

{
	"error": {
		"_tag": "@maple/ingest/OrgQueueThrottled",
		"type": "rate_limit_error",
		"code": "ingest_queue_throttled",
		"title": "Ingest queue full for this org",
		"message": "This org's ingest queue is at capacity. No data was written; resend this batch after the suggested delay.",
		"retryable": true,
		"recovery": "retry",
		"retry_after_seconds": 1
	}
}

Checks run roughly in the order below, so a request fails on the first one it trips.

OpenTelemetry SDKs and the Collector already retry 429 and 503 with backoff, and drop on other 4xx codes. That is the right behavior for every code above except ingest_encode_failed, which an exporter retries even though it cannot succeed.

Batching

A request is limited by its compressed size (20 MiB), not its span or record count. The default batch sizes of the OpenTelemetry SDKs (512 spans or log records per export) and of the Collector’s batch processor (8,192 items) stay far below that. If you raise them and a batch reaches the limit, the gateway answers 413 and the exporter drops the whole batch.

Related

• OpenTelemetry conventions: the attributes Maple reads from what you send
• Instrumentation guides: per-language exporter setup
• Limits: query ranges, SQL and API rate limits
• Regions: US and EU hosts