API Reference

MiniAPM provides a simple HTTP API for ingesting traces, errors, and deploy information. All ingestion endpoints are served by the collector service (default port 3000).

Authentication

All ingestion endpoints require API key authentication via the Authorization header:

Authorization: Bearer proj_abc123...

Base URL

All endpoints are relative to your MiniAPM collector URL:

http://localhost:3000

Endpoints Overview

Endpoint	Method	Description
/ingest/v1/traces	POST	Ingest OTLP traces
/ingest/errors	POST	Report a single error
/ingest/errors/batch	POST	Report multiple errors
/ingest/deploys	POST	Record a deployment
/health	GET	Health check (no auth)

Common Response Codes

Code	Description
202	Accepted (ingestion endpoints)
200	Success (health check)
401	Missing or invalid API key
400	Invalid request body
500	Server error

OTLP Compatibility

MiniAPM accepts traces in OpenTelemetry Protocol (OTLP) JSON format over HTTP. Configure any OpenTelemetry SDK to export to:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/ingest
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer proj_abc123...

API Sections

• Traces API - OTLP trace ingestion
• Errors API - Error reporting
• Deploys API - Deployment tracking

Quick Examples

Report an Error

curl -X POST http://localhost:3000/ingest/errors \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "exception_class": "RuntimeError",
    "message": "Something went wrong",
    "backtrace": ["app/models/user.rb:42:in `save`"],
    "fingerprint": "user_save_runtime_error"
  }'

Record a Deploy

curl -X POST http://localhost:3000/ingest/deploys \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "git_sha": "abc123def",
    "version": "v1.2.3",
    "deployer": "github-actions"
  }'

Health Check

curl http://localhost:3000/health

# Response:
# {"status":"ok","uptime_seconds":12345,"db_ok":true}