Getting Started

Get started with the LogFlux API in minutes

This guide will help you get started with the LogFlux API quickly.

Prerequisites

A LogFlux account
An API key (get one from your LogFlux Dashboard)
Your encryption secret for securing log data
A tool to make HTTP requests (cURL, Postman, or your programming language of choice)

Choosing Your Endpoint

LogFlux provides customer-specific endpoints to ensure data residency compliance and optimal performance:

Each customer receives a unique subdomain for enhanced security:

EU Region: https://[customer-id].ingest.[region].logflux.io/v1
US Region: https://[customer-id].ingest.[region].logflux.io/v1

Example: https://c12345.ingest.us.logflux.io/v1

Choose based on your data residency requirements and infrastructure location.

Important: Encryption Requirement

All log payloads must be encrypted before sending to LogFlux. We use AES-256-GCM encryption with PBKDF2 key derivation (600,000 iterations) for maximum security.

💡 SDK Recommendation: For production use, we strongly recommend using our official SDKs which handle encryption, retry logic, and error handling automatically.

Your First API Call

While our SDKs handle encryption automatically, here’s the structure of a properly formatted request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


curl -X POST https://c12345.ingest.us.logflux.io/v1/ingest \
  -H "Authorization: Bearer lf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "quickstart",
    "payload": "YWJjZGVmZ2hpams...base64-encrypted-data...",
    "loglevel": 7,
    "timestamp": "2024-01-17T10:30:45Z",
    "encryption_mode": 1,
    "iv": "dGVzdGl2MTIzNDU2",
    "salt": "c2FsdDMyYnl0ZXNsb25nZm9ya2V5ZGVyaXZhdGlvbg=="
  }'

You should receive a response like:

1
2
3
4
5


{
  "status": "success",
  "message": "Log entry processed successfully",
  "request_id": "req_abc123def456"
}

Understanding the Basics

Required Fields

Every log entry must include:

node: Identifies which server/service sent the log (max 255 chars)
payload: The encrypted log message (base64 encoded, max 1MB)
loglevel: Severity level (1-8, see below)
timestamp: When the event occurred (ISO 8601 with timezone)
encryption_mode: Must be 1 (AES-256-GCM with PBKDF2)
iv: Initialization vector (base64 encoded, 12 bytes)
salt: Salt for key derivation (base64 encoded, 32 bytes)

Log Levels (Syslog Compatible)

Level	Name	Description
1	EMERGENCY	System is unusable
2	ALERT	Action must be taken immediately
3	CRITICAL	Critical conditions
4	ERROR	Error conditions
5	WARNING	Warning conditions
6	NOTICE	Normal but significant
7	INFO	Informational messages
8	DEBUG	Debug-level messages

Using the SDKs (Recommended)

Our SDKs handle all the complexity of encryption, retries, and error handling:

Node.js Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const logflux = require('@logflux/logflux-js-sdk');

// Initialize once
logflux.init('https://c12345.ingest.us.logflux.io', 'my-app', 'lf_your_api_key', 'your-secret');

// Send logs - encryption is handled automatically
await logflux.info('Application started successfully');
await logflux.error('Database connection failed');
await logflux.debug('Processing user data');

await logflux.close();

Python Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import logflux

# Initialize once
logflux.init('https://c12345.ingest.us.logflux.io', 'my-app', 'lf_your_api_key', 'your-secret')

# Send logs - encryption is handled automatically
logflux.info('User registered successfully')
logflux.warning('High memory usage detected')
logflux.error('Payment processing failed')

logflux.close()

Go Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import logflux "github.com/logflux-io/logflux-go-sdk"

func main() {
    // Initialize once
    logflux.Init("https://c12345.ingest.us.logflux.io", "my-app", "lf_your_api_key", "your-secret")
    defer logflux.Close()

    // Send logs - encryption is handled automatically
    logflux.Info("Service initialized")
    logflux.Warning("Rate limit approaching")
    logflux.Error("Database connection failed")
}

Java Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import io.logflux.logger.LogFlux;

public class Example {
    public static void main(String[] args) {
        // Initialize once
        LogFlux.init("https://c12345.ingest.us.logflux.io", "my-app", "lf_your_api_key", "your-secret");
        
        // Send logs - encryption is handled automatically
        LogFlux.info("User login successful").join();
        LogFlux.warning("High CPU usage detected").join();
        LogFlux.error("API request failed").join();
        
        LogFlux.close();
    }
}

Direct API Integration (Advanced)

If you need to integrate directly with the API without using our SDKs, you’ll need to:

Implement AES-256-GCM encryption with proper IV generation
Use PBKDF2 key derivation with 600,000 iterations
Handle base64 encoding for payload, IV, and salt
Implement retry logic with exponential backoff
Handle rate limiting (600 requests/minute per API key)

Here’s a conceptual example in Python showing the encryption process:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


import base64
import os
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend

def encrypt_log(message, secret):
    # Generate random salt and IV
    salt = os.urandom(32)
    iv = os.urandom(12)
    
    # Derive key using PBKDF2
    kdf = PBKDF2HMAC(
        algorithm=hashes.SHA256(),
        length=32,
        salt=salt,
        iterations=600000,
        backend=default_backend()
    )
    key = kdf.derive(secret.encode())
    
    # Encrypt using AES-256-GCM
    cipher = Cipher(
        algorithms.AES(key),
        modes.GCM(iv),
        backend=default_backend()
    )
    encryptor = cipher.encryptor()
    ciphertext = encryptor.update(message.encode()) + encryptor.finalize()
    
    # Return base64-encoded values
    return {
        'payload': base64.b64encode(ciphertext + encryptor.tag).decode(),
        'iv': base64.b64encode(iv).decode(),
        'salt': base64.b64encode(salt).decode()
    }

# Usage
encrypted = encrypt_log("User login successful", "your-secret")
# Now send encrypted['payload'], encrypted['iv'], and encrypted['salt'] to the API

Batch Operations

For high-volume logging, use the batch endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


curl -X POST https://c12345.ingest.us.logflux.io/v1/batch \
  -H "Authorization: Bearer lf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "node": "app-server",
        "payload": "YWJjZGVmZ2hpams...",
        "loglevel": 7,
        "timestamp": "2024-01-17T10:30:45Z",
        "encryption_mode": 1,
        "iv": "dGVzdGl2MTIzNDU2",
        "salt": "c2FsdDMyYnl0ZXNsb25nZm9ya2V5ZGVyaXZhdGlvbg=="
      },
      {
        "node": "app-server",
        "payload": "WFlaZGVmZ2hpams...",
        "loglevel": 5,
        "timestamp": "2024-01-17T10:30:46Z",
        "encryption_mode": 1,
        "iv": "YW5vdGhlcml2MTIz",
        "salt": "ZGlmZmVyZW50c2FsdDMyYnl0ZXNmb3JrZXlkZXJpdmU="
      }
    ]
  }'

Limit: Maximum 100 entries per batch

Working with Postman

Download our Postman Collection
Import it into Postman
Set your API key in the collection variables
Remember: You’ll need to encrypt payloads before sending

Best Practices

1. Use Appropriate Log Levels

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// DEBUG (8) - Detailed information for debugging
logflux.debug("Cache lookup for key: user_123");

// INFO (7) - General informational messages
logflux.info("User login successful");

// WARNING (5) - Warning conditions
logflux.warning("API rate limit approaching: 80% used");

// ERROR (4) - Error conditions
logflux.error("Payment gateway timeout after 3 retries");

// CRITICAL (3) - Critical conditions
logflux.critical("Database connection pool exhausted");

2. Include Structured Data

1
2
3
4
5
6
7


// Good: Structured JSON for better searchability
logflux.info(JSON.stringify({
  event: "user_login",
  user_id: "123",
  username: "john",
  ip: "192.168.1.1"
}));

3. Handle Errors Gracefully

1
2
3
4
5
6


// Use resilient client with failsafe mode
const client = new ResilientClient({
  failsafeMode: true,  // Never crash your app
  queueSize: 1000,     // Buffer logs during outages
  // ... other config
});

4. Monitor Rate Limits

1
2
3


X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705493445

Error Handling

Common error responses:

1
2
3
4
5
6
7
8
9


{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": "API key must start with 'lf_'"
  },
  "request_id": "req_abc123def456"
}

Code	Status	Description
`INVALID_API_KEY`	401	Invalid or missing API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INVALID_LOG_LEVEL`	400	Log level out of range (1-8)
`INVALID_ENCRYPTION_MODE`	400	Only mode 1 is supported

Next Steps

Read the full API Reference
Download the OpenAPI Specification
Explore our SDKs for easier integration
Learn about security best practices

Need Help?

Check our Documentation
Contact support@logflux.io