My App

API Reference

Complete REST API documentation for direct HTTP usage

REST API Reference

The Lit Status server provides a comprehensive REST API for managing functions and retrieving metrics. Use these endpoints directly via HTTP or through the TypeScript SDK wrapper.

Authentication

All endpoints require authentication via API key in the header:

X-API-Key: your-api-key-here

API Key Access Rights

The system supports two types of API keys with different permissions:

  • Read-Only Keys: Can access GET endpoints only (view data, metrics, health checks)
  • Full Access Keys: Can access all endpoints including POST operations (create functions, log executions)

Base URL

http://localhost:3000

💡 Tip: If you're using TypeScript, consider using the SDK wrapper instead of making direct HTTP calls for better type safety and error handling.

Endpoints

Health Check

Check server status and authentication configuration.

GET /health

CURL Example:

curl -X GET "http://localhost:3000/health" \
  -H "X-API-Key: your-api-key-here"

Response:

{
  "status": "ok",
  "connected": true,
  "authentication": {
    "enabled": true,
    "readOnlyKeysConfigured": 2,
    "fullAccessKeysConfigured": 1
  }
}

Functions

Create or Update Function

Register a new function or update an existing one.

POST /functions
Content-Type: application/json

CURL Example:

curl -X POST "http://localhost:3000/functions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "name": "sendTransaction",
    "network": "mainnet",
    "product": "lit-node",
    "description": "Send blockchain transaction",
    "isActive": true
  }'

Request Body:

{
  "name": "sendTransaction",
  "network": "mainnet",
  "product": "lit-node",
  "description": "Send blockchain transaction",
  "isActive": true
}

Response (201):

{
  "id": "clw123456789",
  "name": "sendTransaction",
  "network": "mainnet",
  "product": "lit-node",
  "description": "Send blockchain transaction",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Get Function

Retrieve a specific function by name, network, and product.

GET /functions/{name}/{network}/{product}

CURL Example:

curl -X GET "http://localhost:3000/functions/sendTransaction/mainnet/lit-node" \
  -H "X-API-Key: your-api-key-here"

Parameters:

  • name - Function name
  • network - Network identifier
  • product - Product identifier

Response (200):

{
  "id": "clw123456789",
  "name": "sendTransaction",
  "network": "mainnet", 
  "product": "lit-node",
  "description": "Send blockchain transaction",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Get All Functions

List all functions with optional filtering.

GET /functions?includeInactive=false

CURL Examples:

# Get active functions only
curl -X GET "http://localhost:3000/functions" \
  -H "X-API-Key: your-api-key-here"

# Include inactive functions
curl -X GET "http://localhost:3000/functions?includeInactive=true" \
  -H "X-API-Key: your-api-key-here"

Query Parameters:

  • includeInactive (optional) - Include inactive functions (default: false)

Response (200):

[
  {
    "id": "clw123456789",
    "name": "sendTransaction",
    "network": "mainnet",
    "product": "lit-node",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
]

Execution Logs

Log Execution

Record a function execution result.

POST /functions/{functionId}/logs
Content-Type: application/json

CURL Examples:

# Log successful execution
curl -X POST "http://localhost:3000/functions/clw123456789/logs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "isSuccess": true,
    "responseTimeMs": 250
  }'

# Log failed execution
curl -X POST "http://localhost:3000/functions/clw123456789/logs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "isSuccess": false,
    "errorMessage": "Transaction failed: insufficient funds",
    "responseTimeMs": 300
  }'

Request Body (Success):

{
  "isSuccess": true,
  "responseTimeMs": 250
}

Request Body (Failure):

{
  "isSuccess": false,
  "errorMessage": "Transaction failed: insufficient funds",
  "responseTimeMs": 300
}

Response (201):

{
  "id": "clw987654321",
  "functionId": "clw123456789",
  "isSuccess": true,
  "errorMessage": null,
  "responseTimeMs": 250,
  "createdAt": "2024-01-15T10:35:00.000Z"
}

Metrics

Function Metrics

Get aggregated metrics for a specific function.

GET /functions/{functionId}/metrics?startDate=2024-01-01&endDate=2024-01-31

CURL Examples:

# Get all-time metrics
curl -X GET "http://localhost:3000/functions/clw123456789/metrics" \
  -H "X-API-Key: your-api-key-here"

# Get metrics for date range
curl -X GET "http://localhost:3000/functions/clw123456789/metrics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: your-api-key-here"

Query Parameters:

  • startDate (optional) - ISO date string
  • endDate (optional) - ISO date string

Response (200):

{
  "functionId": "clw123456789",
  "totalExecutions": 1250,
  "successfulExecutions": 1200,
  "failedExecutions": 50,
  "averageResponseTime": 245.5,
  "uptime": 96.0,
  "lastExecutionTime": "2024-01-15T10:35:00.000Z"
}

Time-Series Metrics

Get bucketed time-series data for charting.

GET /functions/{functionId}/metrics/timeseries?granularity=hour&startDate=2024-01-15

CURL Examples:

# Hourly metrics for today
curl -X GET "http://localhost:3000/functions/clw123456789/metrics/timeseries?granularity=hour&startDate=2024-01-15" \
  -H "X-API-Key: your-api-key-here"

# Daily metrics for last month
curl -X GET "http://localhost:3000/functions/clw123456789/metrics/timeseries?granularity=day&startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: your-api-key-here"

Query Parameters:

  • granularity (optional) - minute, hour, day, week, month
  • startDate (optional) - ISO date string
  • endDate (optional) - ISO date string

Response (200):

{
  "functionId": "clw123456789",
  "granularity": "hour",
  "timeRange": {
    "startDate": "2024-01-15T00:00:00.000Z",
    "endDate": "2024-01-15T23:59:59.999Z"
  },
  "buckets": [
    {
      "timestamp": "2024-01-15T10:00:00.000Z",
      "totalExecutions": 45,
      "successfulExecutions": 43,
      "failedExecutions": 2,
      "averageResponseTime": 230.5,
      "successRate": 95.6
    }
  ],
  "summary": {
    "functionId": "clw123456789",
    "totalExecutions": 1250,
    "successfulExecutions": 1200,
    "failedExecutions": 50,
    "averageResponseTime": 245.5,
    "uptime": 96.0,
    "lastExecutionTime": "2024-01-15T10:35:00.000Z"
  }
}

All Functions Metrics

Get metrics for all functions.

GET /metrics?startDate=2024-01-01&endDate=2024-01-31

CURL Examples:

# Get all functions metrics
curl -X GET "http://localhost:3000/metrics" \
  -H "X-API-Key: your-api-key-here"

# Get metrics for date range
curl -X GET "http://localhost:3000/metrics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: your-api-key-here"

Query Parameters:

  • startDate (optional) - ISO date string
  • endDate (optional) - ISO date string

Response (200):

[
  {
    "functionId": "clw123456789",
    "totalExecutions": 1250,
    "successfulExecutions": 1200,
    "failedExecutions": 50,
    "averageResponseTime": 245.5,
    "uptime": 96.0,
    "lastExecutionTime": "2024-01-15T10:35:00.000Z"
  }
]

Metrics Export

Export Metrics

Export metrics in Prometheus or JSON format with filtering.

GET /metrics/export?format=prometheus&network=mainnet&product=lit-node

CURL Examples:

# Export all metrics in Prometheus format
curl -X GET "http://localhost:3000/metrics/export" \
  -H "X-API-Key: your-api-key-here"

# Export metrics for specific network/product in JSON
curl -X GET "http://localhost:3000/metrics/export?format=json&network=mainnet&product=lit-node" \
  -H "X-API-Key: your-api-key-here"

# Export filtered metrics with date range
curl -X GET "http://localhost:3000/metrics/export?format=prometheus&network=mainnet&startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: your-api-key-here"

Query Parameters:

  • format - prometheus or json (default: prometheus)
  • network (optional) - Filter by network
  • product (optional) - Filter by product
  • function (optional) - Filter by function name
  • includeInactive (optional) - Include inactive functions
  • startDate (optional) - ISO date string
  • endDate (optional) - ISO date string

Prometheus Response:

# HELP lit_status_function_total_executions Total number of function executions
# TYPE lit_status_function_total_executions counter
lit_status_function_total_executions{function="sendTransaction",network="mainnet",product="lit-node"} 1250

# HELP lit_status_function_uptime Function uptime percentage
# TYPE lit_status_function_uptime gauge
lit_status_function_uptime{function="sendTransaction",network="mainnet",product="lit-node"} 96.0

Get Filter Options

Get available filter values for metrics export.

GET /metrics/filters

CURL Example:

curl -X GET "http://localhost:3000/metrics/filters" \
  -H "X-API-Key: your-api-key-here"

Response (200):

{
  "networks": ["mainnet", "testnet", "goerli"],
  "products": ["lit-node", "vincent-registry", "my-app"],
  "functions": ["sendTransaction", "checkBalance", "authenticate"],
  "totalFunctions": 15,
  "activeFunctions": 12,
  "inactiveFunctions": 3
}

Error Responses

All endpoints may return these error responses:

400 Bad Request

{
  "error": "Missing required fields: name, network, and product are required"
}

401 Unauthorized

{
  "error": "API key required",
  "details": "Please provide an API key in the 'x-api-key' header"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "details": "Read-only API key cannot perform write operations. Use a full access key for this endpoint."
}

404 Not Found

{
  "error": "Function not found",
  "details": "No function found with name: sendTx, network: mainnet, product: lit-node"
}

500 Internal Server Error

{
  "error": "Failed to create or update function",
  "details": "Database connection error"
}

Overview

Introduction to Lit Status monitoring system

Authentication

Configure API keys and permissions for your Lit Status server