REST API Reference

Use the REST API directly when an SDK is not available for your language, or for scripting, CI/CD pipelines, and testing.

Authentication

Base URL: https://api.lognitor.com/api/v1

Include your API key in the X-API-Key header on every request (except heartbeat, which uses a token in the URL).

Send Logs

Send one or more log entries in a batch.

Terminal

curl -X POST $https://api.lognitor.com/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
"batch_id": "550e8400-e29b-41d4-a716-446655440000",
"logs": [
{
  "level": "info",
  "message": "User signed up",
  "timestamp": "2026-04-28T12:00:00.000Z",
  "service": "auth-service",
  "environment": "production",
  "version": "1.2.0",
  "metadata": { "user_email": "alice@example.com", "plan": "pro" },
  "tags": ["signup", "marketing"]
}
]
  }'

Success Response (200)

JSON

{
  "accepted": 1,
  "message": "Logs accepted",
  "rejected": 0,
  "errors": []
}

Validation Error Response (422)

JSON

{
  "accepted": 0,
  "message": "Logs accepted",
  "rejected": 1,
  "errors": [
{ "index": 0, "code": "VALIDATION_ERROR", "field": "level", "message": "Invalid log level" }
  ]
}

Full Log Payload Reference

Only level, message, and timestamp are required. Everything else is optional.

JSON

{
  "level": "error",
  "message": "Payment processing failed",
  "timestamp": "2026-04-28T12:00:00.000Z",
  "service": "payment-service",
  "environment": "production",
  "version": "2.1.0",
  "user_id": "user_123",
  "user": { "id": "user_123", "email": "alice@example.com", "name": "Alice" },
  "metadata": { "order_id": "ord_456", "amount": 99.99, "gateway": "stripe" },
  "tags": ["payment", "critical"],
  "error": {
"type": "PaymentError",
"message": "Card declined",
"stack": "PaymentError: Card declined\n  at processPayment (payment.js:42)"
  },
  "request": {
"method": "POST", "url": "/api/orders/create", "path": "/api/orders/create",
"status_code": 500, "duration_ms": 1250, "ip": "203.0.113.1",
"user_agent": "Mozilla/5.0..."
  },
  "perf": { "duration_ms": 1250, "memory_mb": 128, "db_queries": 5, "cache_hits": 3 },
  "trace": { "trace_id": "abc123def456", "span_id": "span_789", "parent_span_id": "span_456" },
  "deploy": { "commit": "a1b2c3d", "branch": "main", "deployed_by": "github-actions" },
  "breadcrumbs": [
{ "type": "http", "category": "fetch", "message": "GET /api/inventory 200", "level": "info", "timestamp": "2026-04-28T11:59:59.500Z", "data": { "duration_ms": 45 } }
  ],
  "fingerprint": "sha256-hash-for-dedup",
  "action": "order.create",
  "session_id": "sess_abc",
  "release_id": "rel_v2",
  "request_id": "req_xyz",
  "source": "payment-service.ts:42",
  "notify": true,
  "notify_channels": ["slack", "email"]
}

Send Request Logs

Send structured HTTP request data for request analytics.

Terminal

curl -X POST $https://api.lognitor.com/api/v1/ingest/requests \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
"requests": [
{
  "method": "GET", "path": "/api/users", "status_code": 200,
  "duration_ms": 45, "request_id": "req_abc123",
  "timestamp": "2026-04-28T12:00:00.000Z",
  "route": "/api/users", "host": "api.example.com",
  "service": "api-gateway"
}
]
  }'

Request Log Fields

Field	Type	Required	Description
`method`	`string`	Yes	HTTP method (GET, POST, etc).
`path`	`string`	Yes	Request path.
`status_code`	`int`	Yes	HTTP response status.
`duration_ms`	`float`	Yes	Request duration in ms.
`request_id`	`string`	Yes	Unique request identifier.
`timestamp`	`string`	Yes	ISO 8601 timestamp.
`route`	`string`	No	Route pattern (e.g. `/api/users/:id`).
`host`	`string`	No	Server hostname.
`service`	`string`	No	Service name.
`environment`	`string`	No	Environment label.

Submit Feedback

Terminal

curl -X POST $https://api.lognitor.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"comments": "The page crashed when I clicked the submit button",
"name": "Alice",
"email": "alice@example.com"
  }'

Field	Type	Required	Description
`event_id`	`string`	Yes	The log ID to attach feedback to.
`comments`	`string`	Yes	User's feedback text.
`name`	`string`	No	User's name.
`email`	`string`	No	User's email.

Register Release

Terminal

curl -X POST $https://api.lognitor.com/api/v1/releases/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
"version": "2.1.0",
"commit_hash": "a1b2c3d4e5f6",
"branch": "main",
"deployed_by": "github-actions",
"changelog": "Fixed checkout bug, improved search performance"
  }'

Include release_id from the response in subsequent logs to link them to this release.

Field	Type	Required	Description
`version`	`string`	Yes	Release version.
`commit_hash`	`string`	No	Git commit hash.
`branch`	`string`	No	Git branch.
`deployed_by`	`string`	No	Who/what triggered the deploy.
`changelog`	`string`	No	Human-readable changes.

Heartbeat Ping

Ping a heartbeat monitor to signal that a cron job or background task is alive. No body or X-API-Key header needed — the token in the URL is the authentication.

Terminal

curl -X POST $https://api.lognitor.com/api/v1/heartbeat/your-monitor-token

Use in Cron Jobs

Terminal

# Crontab entry — pings after job completes
0 * * * * /usr/bin/sync-inventory && curl -s -X POST $https://api.lognitor.com/api/v1/heartbeat/your-monitor-token

Error Handling

401 Unauthorized

JSON

{ "detail": [{ "msg": "Invalid API key", "type": "auth_error" }] }

422 Validation Error

JSON

{
  "detail": [
{ "loc": ["body", "logs", 0, "level"], "msg": "field required", "type": "value_error.missing" }
  ]
}

429 Rate Limited

Wait the number of seconds specified in the Retry-After header before retrying.

Scripting Examples

Shell Script

Terminal

#!/bin/bash
API_KEY="your-api-key"
SERVICE="deploy-script"

send_log() {
  local level="$1"
  local message="$2"
  curl -s -X POST $https://api.lognitor.com/api/v1/ingest \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d "{
\"batch_id\": \"$(uuidgen)\",
\"logs\": [{
  \"level\": \"$level\",
  \"message\": \"$message\",
  \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\",
  \"service\": \"$SERVICE\"
}]
}"
}

send_log "info" "Deploy started"
./deploy.sh
if [ $? -eq 0 ]; then
  send_log "info" "Deploy successful"
else
  send_log "error" "Deploy failed with exit code $?"
fi

GitHub Actions

YAML

- name: Notify Lognitor
  run: |
curl -s -X POST $https://api.lognitor.com/api/v1/releases/register \
-H "Content-Type: application/json" \
-H "X-API-Key: ${{ secrets.LOGNITOR_API_KEY }}" \
-d '{
  "version": "${{ github.sha }}",
  "commit_hash": "${{ github.sha }}",
  "branch": "${{ github.ref_name }}",
  "deployed_by": "github-actions"
}'