API Reference

MiniAPM provides a simple HTTP API for ingesting traces, errors, and deploy information.

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 server 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
/ingest/requests	POST	Batch HTTP request metrics
/health	GET	Health check (no auth)

Common Response Codes

Code	Description
200	Success
401	Missing or invalid API key
400	Invalid request body
500	Server error

OTLP Compatibility

MiniAPM accepts traces in OpenTelemetry Protocol (OTLP) 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 '{
    "error_type": "RuntimeError",
    "message": "Something went wrong",
    "backtrace": ["app/models/user.rb:42:in `save`"]
  }'

Record a Deploy

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

Health Check

curl http://localhost:3000/health

# Response:
{"status":"ok"}