REST API Reference
Direct HTTP API integration for any language or platform. High-performance JSON-based ingestion with global edge endpoints.
Base URL
https://api.luminalog.cloud/v1All API requests must be made over HTTPS. Plain HTTP requests will be permanently rejected for security.
Authentication
Authentication is performed via the x-api-key header. Your API key provides full access to your organization's logging data.
curl -X POST https://api.luminalog.cloud/v1/logs \
-H "x-api-key: ll_2010ecf83382641e48b090e7fb82396eb130113a51e363da" \
-H "Content-Type: application/json" \
-d '{"logs": [...]}'Security Requirement
x-api-key header. The legacy api_key field in the request body is deprecated and will be removed in v2.Ingest Logs
Manual Ingestion
Send a batch of up to 1,000 log entries to LuminaLog. Batched requests are significantly more efficient than single-log requests.
Request Body Structure
{
"logs": [
{
"timestamp": "2026-01-26T14:30:00.000Z",
"level": "info",
"message": "User logged in",
"environment": "production",
"metadata": {
"user_id": "user-789",
"method": "google-oauth"
}
},
{
"timestamp": "2026-01-26T14:30:05.000Z",
"level": "error",
"message": "Payment failed",
"environment": "production",
"error": {
"type": "PaymentError",
"message": "Insufficient funds",
"stack_trace": ["at processPayment (payment.ts:45)", "at checkout (checkout.ts:120)"]
},
"metadata": { "order_id": "ORD-12345", "amount": 99.99 }
}
]
}Request Schema
| Field | Type | Required | Description |
|---|---|---|---|
| timestamp | string (ISO) | Yes | UTC timestamp of the event |
| level | string | Yes | debug, info, warn, error, fatal |
| message | string | Yes | Primary log message (max 10KB) |
| environment | string | No | Deployment environment name |
| metadata | object | No | Structured JSON data (max 100KB) |
| error | object | No | Detailed error payload with stack traces |
| project_id | string | No | Optional internal project identifier |
Error Payload Schema
Required for optimal AI-powered debugging and error grouping.
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | No | e.g., "TypeError", "AuthError" |
| message | string | No | The raw error message string |
| stack_trace | array | No | Array of stack trace strings |
| context | object | No | Associated error-specific metadata |
Response Schema
{
"message": "Logs ingested successfully",
"processed": 2,
"bytes_used": 1024
}| Field | Type | Description |
|---|---|---|
| message | string | Success notification string |
| processed | number | Total number of logs successfully accepted |
| bytes_used | number | Total data size deducted from your quota |
Status Codes
200 OK
Logs ingested successfully.
400 Bad Request
Invalid payload or missing required fields.
401 Unauthorized
Invalid or missing API key.
429 Rate Limit
Rate limit exceeded or quota exhausted.
500 Error
Internal server error. Retry with backoff.
Language Examples
cURL
curl -X POST https://api.luminalog.cloud/v1/logs \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"logs": [
{
"timestamp": "2026-01-26T14:30:00Z",
"level": "info",
"message": "API Request Received",
"metadata": { "user_id": "user_789" }
}
]
}'JavaScript (Fetch)
const response = await fetch('https://api.luminalog.cloud/v1/logs', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
logs: [{
timestamp: new Date().toISOString(),
level: 'info',
message: 'Node.js event logging',
metadata: { server: 'aws-us-east-1' }
}]
})
});Python (Requests)
import requests
from datetime import datetime
response = requests.post(
'https://api.luminalog.cloud/v1/logs',
headers={
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'logs': [{
'timestamp': datetime.utcnow().isoformat() + 'Z',
'level': 'info',
'message': 'Python script event'
}]
}
)Rate Limits
API requests are subject to hierarchical rate limits. We utilize a token bucket algorithm to handle traffic burstability.
Response Headers
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset