API reference

HTTP API for ingesting and reading logs — authenticated with your project Bearer token.

Base URL is your LoggerMan deployment origin, e.g. https://app.example.com. All paths below are relative to that host.

Authentication

Send Authorization: Bearer <project_token> on every request. Tokens are managed under Settings → API keys. Invalid or missing tokens return 401 or 403.

POST — Create log

Ingest a new log entry for a project.

Request

POST /api/projects/{projectId}/logs
Authorization: Bearer {token}
Content-Type: application/json

{
  "message": "User signed in",
  "type": "INFO",
  "criticality": "LOW",
  "source": "auth-service",
  "metadata": {
    "userId": "user_abc",
    "plan": "pro"
  }
}

Body fields

Field	Required	Values
`message`	Yes	String — primary log text
`type`	No	`INFO` \| `WARNING` \| `ERROR`
`criticality`	No	`LOW` \| `MEDIUM` \| `HIGH`
`source`	No	String label for filtering
`metadata`	No	JSON object (arbitrary key/value)

All ingest fields are sanitized server-side: HTML tags and dangerous URL schemes are stripped, control/bidi characters removed, and metadata is limited to a plain JSON object (no __proto__or nested functions). Messages over 8 KB or metadata over 16 KB are rejected.

Success: 201 Created with the log JSON body.

Errors: 400 validation, 401 missing token, 403 unauthorized project/token, 500 server failure.

Example response

{
  "id": "...",
  "projectId": "...",
  "message": "User signed in",
  "type": "INFO",
  "criticality": "LOW",
  "status": "ACTIVE",
  "source": "auth-service",
  "metadata": { "userId": "user_abc", "plan": "pro" },
  "timestamp": "2025-06-03T12:00:00.000Z",
  "createdAt": "...",
  "updatedAt": "..."
}

POST — Batch ingest

Send up to 100 logs in one request. Same auth and field rules as single ingest. Body may be a JSON array or { "logs": [ ... ] }. Each item may use level (debug, info, warn, error) instead of type.

Request

POST /api/projects/{projectId}/logs/batch
Authorization: Bearer {token}
Content-Type: application/json

{
  "logs": [
    { "message": "Worker started", "level": "info", "source": "worker" },
    { "message": "Disk 90% full", "level": "warn", "metadata": { "pct": 90 } }
  ]
}

Success: 201 Created with accepted count and created log objects.

POST — Incoming webhook

Create a webhook in Settings → Integration. Each hook gets a unique token in the URL. No Bearer auth — the token in the path identifies the hook.

Request

POST /api/projects/{projectId}/hooks/{hookToken}
Content-Type: application/json

{
  "message": "Zapier trigger fired",
  "level": "info",
  "metadata": { "zap": "new-error" }
}

Arbitrary JSON is accepted; common fields (message, level, source, metadata) are mapped automatically. Success: 201 Created with the log body.

POST — OTLP logs

Ingest an OpenTelemetry logs export JSON payload. Severity is mapped to LoggerMan type and criticality.

Request

POST /api/projects/{projectId}/otlp
Authorization: Bearer {token}
Content-Type: application/json

{ "resourceLogs": [ ... ] }

Use the Integration tab for a full example export. Same rate limits as single log ingest apply.

Ingest queue (202)

When per-minute ingest limits are exceeded, LoggerMan returns 202 Accepted with code: "QUEUED" instead of dropping payloads. Higher plans dequeue first: Scale, then Team, then Starter. See Platform docs.

Structured error responses

Ingest endpoints return JSON errors with a machine-readable code field when validation or limits fail:

`code`	HTTP	Meaning
`UNAUTHORIZED`	401	Missing Bearer token
`FORBIDDEN`	403	Invalid project, token, or webhook
`VALIDATION_ERROR`	400	Invalid body or fields
`INVALID_JSON`	400	Body is not valid JSON
`PAYLOAD_TOO_LARGE`	413	Batch over 100 logs or size limits exceeded
`RATE_LIMITED`	429	Rate limit — retry after `Retry-After` header

The SDK reads these codes when retry is enabled and queues retries on rate limits and network failures.

GET — List logs

Retrieve logs for a project (paginated).

Request

GET /api/projects/{projectId}/logs
Authorization: Bearer {token}
page: 0

Headers

Header	Required	Description
`Authorization`	Yes	Bearer project token
`page`	No	Zero-based page index (default 0). Must be numeric if sent.

Success: 200 OK with a JSON array of log objects.

Unauthorized: 403 with empty array when token does not match the project.

Rate and payload guidance

Keep messages concise; put bulk data in metadata.
Prefer the SDK — it sets JSON headers and surfaces HTTP errors.
Do not log secrets, passwords, or raw payment card data.