Log Messages API

The Log Messages API provides endpoints for retrieving, creating, and monitoring activity logs across the LedgerLink platform.

Base URL: https://api.ledgerlink.ai/v1/tracker

---

Get Log Messages

Retrieve filtered and paginated log messages with advanced querying capabilities.

Endpoint

GET /log-messages

Query Parameters

Parameter	Type	Required	Description
offset	integer	No	Page number for pagination (default: 0)
limit	integer	No	Number of records per page (default: 20, max: 100)
sortBy	string	No	Field to sort by (e.g., "timestamp", "service", "status")
sortOrder	string	No	Sort direction: "asc" or "desc" (default: "desc")
service	string	No	Filter by service name (e.g., "LinkCore", "LinkQuote")
requestId	string	No	Filter by specific request ID
startDate	string	No	Filter logs after this date (ISO 8601 format)
endDate	string	No	Filter logs before this date (ISO 8601 format)
type	string	No	Filter by event type (e.g., "TRANSACTION_CREATED")
status	string	No	Filter by status: "SUCCESS", "FAILURE", "PENDING"

Request Example

curl -X GET "https://api.ledgerlink.ai/v1/tracker/log-messages?service=LinkCore&status=SUCCESS&limit=20&offset=0" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_jwt_token_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "log_abc123def456",
      "service": "LinkCore",
      "request_id": "req_xyz789",
      "event_type": "TRANSACTION_CREATED",
      "status": "SUCCESS",
      "timestamp": "2025-11-20T17:30:45.123Z",
      "metadata": {
        "transaction_id": "tx_001234",
        "participant_id": "part_567890",
        "amount": "1500.00",
        "currency": "USD",
        "type": "DEPOSIT"
      }
    },
    {
      "id": "log_def789ghi012",
      "service": "LinkCore",
      "request_id": "req_abc456",
      "event_type": "PARTICIPANT_UPDATED",
      "status": "SUCCESS",
      "timestamp": "2025-11-20T17:29:12.456Z",
      "metadata": {
        "participant_id": "part_567890",
        "updated_fields": ["email", "phone"],
        "updated_by": "admin_user_123"
      }
    }
  ],
  "pagination": {
    "total": 1547,
    "offset": 0,
    "limit": 20,
    "hasMore": true
  }
}

Response Fields

Data Object

Field	Type	Description
id	string	Unique identifier for the log message
service	string	Name of the service that generated the log
request_id	string	Request ID for tracking across services
event_type	string	Type of event (e.g., TRANSACTION_CREATED)
status	string	Status of the event: SUCCESS, FAILURE, PENDING
timestamp	string	ISO 8601 timestamp when the event occurred
metadata	object	Additional context-specific data

Pagination Object

Field	Type	Description
total	integer	Total number of log messages matching the query
offset	integer	Current offset (page number)
limit	integer	Number of records returned per page
hasMore	boolean	Whether more pages are available

Error Responses

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid query parameter",
    "details": [
      {
        "field": "sortOrder",
        "message": "Must be either 'asc' or 'desc'"
      }
    ]
  }
}

401 Unauthorized

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "resetAt": "2025-11-20T18:00:00.000Z"
    }
  }
}

---

Test Log Message

Test endpoint for publishing sample log messages. This is useful for integration testing and verifying your log capture setup.

Endpoint

POST /log-messages/test-add-log-message

Request Body

No request body required. This endpoint generates and publishes a pre-configured test log message.

Request Example

curl -X POST "https://api.ledgerlink.ai/v1/tracker/log-messages/test-add-log-message" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_jwt_token_here"

Response

Status: 200 OK

{
  "message": "Message published successfully at 2025-11-20T17:50:00.000Z",
  "test_data": {
    "service": "ValuationService",
    "request_id": "requestId_98711",
    "event_type": "VALUATION_PROCESSED",
    "status": "SUCCESS",
    "timestamp": "2025-11-20T17:50:00.000Z",
    "metadata": {
      "transaction_id": "tx_56789",
      "value": "65000.00",
      "currency": "USD",
      "details": "Valuation successful for BTC at $65,000"
    }
  }
}

Error Responses

503 Service Unavailable

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Error publishing message to message queue"
  }
}

---

Common Event Types

Link Tracker supports the following standard event types across services:

Transaction Events

• TRANSACTION_CREATED - New transaction initiated
• TRANSACTION_COMPLETED - Transaction successfully completed
• TRANSACTION_FAILED - Transaction failed
• TRANSACTION_CANCELLED - Transaction cancelled by user

Valuation Events

• VALUATION_REQUESTED - Valuation request received
• VALUATION_PROCESSED - Valuation completed successfully
• VALUATION_FAILED - Valuation failed

Participant Events

• PARTICIPANT_CREATED - New participant onboarded
• PARTICIPANT_UPDATED - Participant information updated
• PARTICIPANT_DELETED - Participant removed

Wallet Events

• WALLET_CREATED - New wallet created
• WALLET_BALANCE_UPDATED - Wallet balance changed
• WALLET_TRANSACTION - Wallet transaction executed

System Events

• SERVICE_STARTED - Service initialization
• SERVICE_STOPPED - Service shutdown
• HEALTH_CHECK - Service health check
• ERROR_OCCURRED - System error logged

---

Best Practices

Filtering Large Datasets

When querying large log datasets:

1. Use date ranges to limit the time window
2. Filter by service to scope to specific systems
3. Use pagination to retrieve data in manageable chunks
4. Sort by timestamp for chronological ordering

# Example: Get last 24 hours of LinkCore logs
curl -X GET "https://api.ledgerlink.ai/v1/tracker/log-messages?service=LinkCore&startDate=2025-11-19T17:00:00Z&endDate=2025-11-20T17:00:00Z&sortBy=timestamp&sortOrder=desc&limit=50"

Tracking Request Flows

Use request_id to trace requests across multiple services:

# Track a specific request across all services
curl -X GET "https://api.ledgerlink.ai/v1/tracker/log-messages?requestId=req_xyz789"

Monitoring Error Rates

Query failure logs to monitor system health:

# Get all failures in the last hour
curl -X GET "https://api.ledgerlink.ai/v1/tracker/log-messages?status=FAILURE&startDate=2025-11-20T16:00:00Z"

Metadata Best Practices

When adding custom metadata:

• Keep field names consistent across similar events
• Use snake_case for field naming
• Include relevant context (IDs, amounts, status codes)
• Avoid sensitive data (passwords, API keys, PII)
• Stay within the 32 KB metadata limit

---

Need more help? Check our Error Handling Guide or FAQ for additional information.