K8s Logs API Reference

This guide provides comprehensive documentation for the Kubernetes Logs management API endpoints, including request/response formats and integration examples.

Base URL

https://api.nife.io/v1/k8s/logs

All endpoints are prefixed with this base URL.

Authentication

All requests require authentication via Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain access tokens from the Access Tokens page in the UI.

API Endpoints Overview

Collection Configuration (7 endpoints)

Manage which logs to collect from Kubernetes clusters.

Endpoint	Method	Purpose
`/config`	GET	List collection configurations
`/config`	POST	Create collection configuration
`/config`	PUT	Update configuration
`/config`	DELETE	Delete configuration
`/config/bulk-update`	POST	Bulk update multiple configs
`/config/disable`	POST	Disable collection for namespace
`/config/disable/cluster`	POST	Disable all collection for cluster

Log Retrieval (6 endpoints)

Retrieve and search logs from your clusters.

Endpoint	Method	Purpose
`/`	GET	Get logs with filters
`/search`	POST	Advanced log search
`/search/logql`	POST	Search using LogQL
`/namespaces`	GET	List namespaces
`/pods`	GET	List pods in namespace
`/containers`	GET	List containers in pod

Log Collection (4 endpoints)

Manage on-demand and continuous log collection jobs.

Endpoint	Method	Purpose
`/collect`	POST	Start one-time collection
`/collect/continuous`	POST	Start continuous collection
`/collect/bulk`	POST	Collect from all pods
`/collect/jobs`	GET	List collection jobs

Archive Management (6 endpoints)

Create and manage log archival policies.

Endpoint	Method	Purpose
`/archive/policies`	GET	List archive policies
`/archive/policies`	POST	Create archive policy
`/archive/policies`	PUT	Update policy
`/archive/policies`	DELETE	Delete policy
`/archive/start`	POST	Start archive job
`/archive/jobs`	GET	List archive jobs

S3 Storage (4 endpoints)

Access logs stored in S3.

Endpoint	Method	Purpose
`/s3/metadata`	GET	Get S3 log metadata
`/s3/content`	GET	Get log content from S3
`/s3/stats`	GET	Get S3 storage statistics
`/storage/info`	GET	Get storage configuration

Metrics & Monitoring (3 endpoints)

Monitor log collection and system health.

Endpoint	Method	Purpose
`/metrics`	GET	Get general log metrics
`/clusters/{clusterId}/metrics`	GET	Get cluster-specific metrics
`/stats`	GET	Get log statistics
`/health`	GET	Get system health

Cluster Management (6 endpoints)

Manage cluster connections and configuration.

Endpoint	Method	Purpose
`/clusters/status`	GET	Get cluster status
`/clusters/configs`	GET	Get cluster configurations
`/clusters/configs`	POST	Create cluster config
`/clusters/configs`	PUT	Update cluster config
`/clusters/configs`	DELETE	Delete cluster config
`/clusters/refresh`	POST	Refresh cluster connections

Detailed Endpoint Reference

Create Collection Configuration

POST /config

Create a new log collection configuration for a Kubernetes cluster.

Request Body:

{
  "cluster_id": "cluster-123",
  "namespace": "production",
  "app_filter": "api-server",
  "log_levels": ["info", "warn", "error"],
  "collection_interval": 300,
  "exclude_namespaces": ["kube-system", "kube-public"],
  "max_logs_per_collection": 1000,
  "is_enabled": true
}

Response (201):

{
  "success": true,
  "data": {
    "id": "config-456",
    "user_id": "user-789",
    "org_id": "org-012",
    "cluster_id": "cluster-123",
    "namespace": "production",
    "app_filter": "api-server",
    "log_levels": ["info", "warn", "error"],
    "collection_interval": 300,
    "exclude_namespaces": ["kube-system", "kube-public"],
    "max_logs_per_collection": 1000,
    "is_enabled": true,
    "created_at": "2024-01-06T10:30:00Z",
    "updated_at": "2024-01-06T10:30:00Z"
  }
}

List Collection Configurations

GET /config

List all collection configurations, optionally filtered by cluster or namespace.

Query Parameters:

?cluster_id=cluster-123&namespace=production

Response (200):

{
  "success": true,
  "data": {
    "configs": [
      {
        "id": "config-456",
        "cluster_id": "cluster-123",
        "namespace": "production",
        "app_filter": "api-server",
        "is_enabled": true,
        "created_at": "2024-01-06T10:30:00Z"
      }
    ]
  }
}

Update Collection Configuration

PUT /config

Update an existing collection configuration.

Query Parameters:

?cluster_id=cluster-123

Request Body:

{
  "id": "config-456",
  "cluster_id": "cluster-123",
  "namespace": "production",
  "app_filter": "api-gateway",
  "log_levels": ["warn", "error"],
  "collection_interval": 600,
  "is_enabled": true
}

Response (200):

{
  "success": true,
  "data": {
    "id": "config-456",
    "cluster_id": "cluster-123",
    "namespace": "production",
    "is_enabled": true,
    "updated_at": "2024-01-06T11:00:00Z"
  }
}

Bulk Update Configurations

POST /config/bulk-update

Enable or disable multiple configurations in a single request.

Request Body:

{
  "configs": [
    {
      "cluster_id": "cluster-123",
      "namespace": "production",
      "is_enabled": true
    },
    {
      "cluster_id": "cluster-123",
      "namespace": "staging",
      "is_enabled": false
    }
  ]
}

Response (200):

{
  "success": true,
  "data": {
    "updated": 2,
    "message": "2 configurations updated successfully"
  }
}

Search Logs

POST /search

Advanced log search with flexible criteria.

Request Body:

{
  "cluster_id": "cluster-123",
  "namespace": "production",
  "pod": "api-server-1",
  "container": "api",
  "level": "error",
  "start_time": "2024-01-06T00:00:00Z",
  "end_time": "2024-01-06T23:59:59Z",
  "limit": 100,
  "query": "database connection"
}

Response (200):

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log-001",
        "timestamp": "2024-01-06T10:35:22Z",
        "level": "error",
        "namespace": "production",
        "pod": "api-server-1",
        "container": "api",
        "message": "Connection timeout to database"
      }
    ],
    "total_count": 45,
    "has_more": true
  }
}

Search with LogQL

POST /search/logql

Execute LogQL queries for advanced log analysis.

Request Body:

{
  "cluster_id": "cluster-123",
  "query": "{namespace=\"production\"} |= \"error\" | json | status >= 500",
  "start_time": "2024-01-06T00:00:00Z",
  "end_time": "2024-01-06T23:59:59Z",
  "limit": 100
}

Response (200):

{
  "success": true,
  "data": {
    "logs": [],
    "total_count": 23
  }
}

List Namespaces

GET /namespaces

Get all available namespaces in a cluster.

Query Parameters:

?cluster_id=cluster-123

Response (200):

{
  "success": true,
  "data": {
    "namespaces": [
      "production",
      "staging",
      "development",
      "default",
      "kube-system"
    ],
    "count": 5
  }
}

Start Log Collection

POST /collect

Start an immediate log collection from specific pods.

Request Body:

{
  "app_id": "app-123",
  "namespace": "production",
  "pods": ["api-server-1", "api-server-2"],
  "containers": ["api"],
  "since": "1h",
  "tail": 1000
}

Response (201):

{
  "success": true,
  "data": {
    "job_id": "job-789",
    "message": "Collection job started successfully"
  }
}

Create Archive Policy

POST /archive/policies

Create an automatic log archival policy.

Request Body:

{
  "name": "Production 90-Day Archive",
  "retention_days": 90,
  "compression_type": "gzip",
  "storage_location": "s3://my-bucket/logs",
  "is_active": true,
  "app_id": "app-123",
  "namespace": "production"
}

Response (201):

{
  "success": true,
  "data": {
    "id": "policy-111",
    "name": "Production 90-Day Archive",
    "retention_days": 90,
    "compression_type": "gzip",
    "is_active": true,
    "created_at": "2024-01-06T10:30:00Z"
  }
}

Get Archive Policies

GET /archive/policies

List all archive policies.

Response (200):

{
  "success": true,
  "data": {
    "policies": [
      {
        "id": "policy-111",
        "name": "Production 90-Day Archive",
        "retention_days": 90,
        "is_active": true
      }
    ]
  }
}

Start Archive Job

POST /archive/start

Manually trigger an archive job for a policy.

Request Body:

{
  "policy_id": "policy-111"
}

Response (201):

{
  "success": true,
  "data": {
    "job_id": "archive-job-222"
  }
}

Get Archive Jobs

GET /archive/jobs

List archive jobs.

Query Parameters:

?policy_id=policy-111&status=completed

Response (200):

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "archive-job-222",
        "policy_id": "policy-111",
        "status": "completed",
        "start_time": "2024-01-06T10:00:00Z",
        "end_time": "2024-01-06T10:45:00Z",
        "logs_archived": 150000,
        "size_bytes": 456789000,
        "error": null
      }
    ]
  }
}

Get S3 Log Metadata

GET /s3/metadata

List log files stored in S3.

Query Parameters:

?cluster_id=cluster-123&namespace=production&start_time=2024-01-01T00:00:00Z

Response (200):

{
  "success": true,
  "data": {
    "metadata": [
      {
        "id": "s3-meta-001",
        "cluster_id": "cluster-123",
        "namespace": "production",
        "pod_name": "api-server-1",
        "container_name": "api",
        "s3_key": "logs/production/api-server-1-2024-01-06.json.gz",
        "s3_bucket": "my-logs-bucket",
        "start_time": "2024-01-06T00:00:00Z",
        "end_time": "2024-01-06T23:59:59Z",
        "log_count": 10000,
        "size_bytes": 2048000,
        "compressed": true,
        "created_at": "2024-01-07T00:15:00Z"
      }
    ],
    "count": 1,
    "storage": "s3"
  }
}

Get S3 Statistics

GET /s3/stats

Get aggregate statistics about S3-stored logs.

Response (200):

{
  "success": true,
  "data": {
    "total_files": 450,
    "total_size": 5368709120,
    "total_logs": 45000000,
    "oldest_log": "2023-07-01T00:00:00Z",
    "newest_log": "2024-01-06T23:59:59Z",
    "by_cluster": {
      "cluster-123": 250,
      "cluster-456": 200
    },
    "by_namespace": {
      "production": 300,
      "staging": 150
    }
  }
}

Get General Metrics

GET /metrics

Get log collection metrics.

Query Parameters:

?app_id=app-123&namespace=production

Response (200):

{
  "success": true,
  "data": {
    "total_logs": 1500000,
    "logs_per_hour": 62500,
    "avg_log_size": 512,
    "storage_used": "768 GB",
    "by_level": {
      "error": 15000,
      "warn": 125000,
      "info": 1200000,
      "debug": 160000
    },
    "by_namespace": {
      "production": 1200000,
      "staging": 300000
    }
  }
}

Get Cluster Status

GET /clusters/status

Get status of all connected clusters.

Response (200):

{
  "success": true,
  "data": {
    "clusters": [
      {
        "cluster_id": "cluster-123",
        "name": "Production Cluster",
        "status": "healthy",
        "last_health_check": "2024-01-06T11:30:00Z",
        "log_collector_status": "active",
        "metrics": {
          "pods_monitored": 150,
          "logs_per_minute": 5000
        }
      }
    ]
  }
}

Get System Health

GET /health

Get overall system health status.

Response (200):

{
  "success": true,
  "data": {
    "status": "healthy",
    "components": {
      "log_collector": {
        "status": "active",
        "last_check": "2024-01-06T11:30:00Z"
      },
      "database": {
        "status": "connected",
        "last_check": "2024-01-06T11:30:00Z"
      },
      "storage": {
        "status": "available",
        "last_check": "2024-01-06T11:30:00Z"
      }
    },
    "uptime": "45d 12h 30m"
  }
}

Error Handling

Common Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_CLUSTER_ID",
    "message": "Cluster not found",
    "details": "The specified cluster ID does not exist or you don't have access"
  }
}

Rate Limiting

API requests are rate-limited:

100 requests per minute for standard endpoints
10 requests per minute for heavy operations (search, archive)

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704545400

Integration Examples

Python Example

import requests
from datetime import datetime, timedelta

BASE_URL = "https://api.nife.io/v1/k8s/logs"
TOKEN = "your_access_token"

headers = {"Authorization": f"Bearer {TOKEN}"}

# Search logs
response = requests.post(
    f"{BASE_URL}/search",
    headers=headers,
    json={
        "cluster_id": "cluster-123",
        "namespace": "production",
        "level": "error",
        "start_time": (datetime.now() - timedelta(days=1)).isoformat(),
        "limit": 100
    }
)

logs = response.json()["data"]["logs"]
print(f"Found {len(logs)} error logs")

JavaScript Example

const axios = require('axios');

const BASE_URL = 'https://api.nife.io/v1/k8s/logs';
const TOKEN = 'your_access_token';

const client = axios.create({
  baseURL: BASE_URL,
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});

// Create archive policy
async function createArchivePolicy() {
  try {
    const response = await client.post('/archive/policies', {
      name: 'Production Archive',
      retention_days: 90,
      compression_type: 'gzip',
      storage_location: 's3://bucket/logs',
      is_active: true
    });
    console.log('Policy created:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

createArchivePolicy();

cURL Examples

# Search logs
curl -X POST https://api.nife.io/v1/k8s/logs/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_id": "cluster-123",
    "namespace": "production",
    "level": "error",
    "limit": 100
  }'

# Create collection config
curl -X POST https://api.nife.io/v1/k8s/logs/config \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_id": "cluster-123",
    "namespace": "production",
    "log_levels": ["error", "warn"],
    "is_enabled": true
  }'

Best Practices

Always use specific filters - Reduce data transfer and improve performance
Set reasonable limits - Start with limit=100, increase only if needed
Use date ranges - Don't retrieve entire log history at once
Handle pagination - Check has_more flag in responses
Cache credentials - Use stored access tokens, don't regenerate frequently
Monitor rate limits - Check headers and implement backoff
Compress archive logs - Always enable compression to reduce costs
Regular cleanup - Archive old logs to reduce database load

For more information, see the User Guide.

Base URL​

Authentication​

API Endpoints Overview​

Collection Configuration (7 endpoints)​

Log Retrieval (6 endpoints)​

Log Collection (4 endpoints)​

Archive Management (6 endpoints)​

S3 Storage (4 endpoints)​

Metrics & Monitoring (3 endpoints)​

Cluster Management (6 endpoints)​

Detailed Endpoint Reference​

Create Collection Configuration​

List Collection Configurations​

Update Collection Configuration​

Bulk Update Configurations​

Search Logs​

Search with LogQL​

List Namespaces​

Start Log Collection​

Create Archive Policy​

Get Archive Policies​

Start Archive Job​

Get Archive Jobs​

Get S3 Log Metadata​

Get S3 Statistics​

Get General Metrics​

Get Cluster Status​

Get System Health​

Error Handling​

Common Status Codes​

Error Response Format​

Rate Limiting​

Integration Examples​

Python Example​

JavaScript Example​

cURL Examples​

Best Practices​

Base URL

Authentication

API Endpoints Overview

Collection Configuration (7 endpoints)

Log Retrieval (6 endpoints)

Log Collection (4 endpoints)

Archive Management (6 endpoints)

S3 Storage (4 endpoints)

Metrics & Monitoring (3 endpoints)

Cluster Management (6 endpoints)

Detailed Endpoint Reference

Create Collection Configuration

List Collection Configurations

Update Collection Configuration

Bulk Update Configurations

Search Logs

Search with LogQL

List Namespaces

Start Log Collection

Create Archive Policy

Get Archive Policies

Start Archive Job

Get Archive Jobs

Get S3 Log Metadata

Get S3 Statistics

Get General Metrics

Get Cluster Status

Get System Health

Error Handling

Common Status Codes

Error Response Format

Rate Limiting

Integration Examples

Python Example

JavaScript Example

cURL Examples

Best Practices