Request Context

Request Metadata

Every API request and response includes rich metadata for debugging, tracing, and analytics. Use request IDs for support tickets and custom headers for advanced use cases.

Unique request IDs

Timing metrics

Cache status

HTTP Headers Reference

Header	Description	Example
`Authorization`required	Bearer token for API authentication	`Bearer jk_live_xxx`
`Content-Type`required	Request body format	`application/json`
`X-Request-Id`	Client-provided request ID for tracking	`req_abc123xyz`
`X-Idempotency-Key`	Unique key for idempotent requests	`idem_order_12345`
`Accept-Currency`	Preferred currency for price responses	`EUR`
`Accept-Language`	Preferred locale for formatting	`de-DE`
`JustKalm-Version`	API version to use	`2024-01-15`
`X-Mock-Scenario`	Trigger mock responses in sandbox	`rate_limit`

Code Examples

Request ID in Response

# Every response includes X-Request-Id
curl -i https://api.justkalm.com/v2/valuate \
  -H "Authorization: Bearer jk_live_xxx" \
  -d '{"url": "https://example.com/product"}'

# Response headers include:
# X-Request-Id: req_7f8g9h0i1j2k3l4m
# X-Response-Time: 234
# X-RateLimit-Remaining: 987

# Use X-Request-Id when contacting support
# "My request req_7f8g9h0i1j2k3l4m failed..."

Custom Request ID

# Provide your own request ID for tracking
curl https://api.justkalm.com/v2/valuate \
  -H "Authorization: Bearer jk_live_xxx" \
  -H "X-Request-Id: myapp_req_12345" \
  -d '{"url": "https://example.com/product"}'

# Response echoes your ID + adds server ID:
# X-Request-Id: myapp_req_12345
# X-JustKalm-Request-Id: req_7f8g9h0i1j2k3l4m

SDK Metadata Access

import { JustKalm } from '@justkalm/sdk';

const client = new JustKalm({ apiKey: process.env.JUSTKALM_API_KEY });

// Access metadata from responses
const result = await client.valuate('https://example.com/product');

console.log(result.metadata);
// {
//   requestId: 'req_7f8g9h0i1j2k3l4m',
//   responseTime: 234,
//   cacheStatus: 'MISS',
//   apiVersion: '2024-01-15',
//   rateLimit: {
//     limit: 1000,
//     remaining: 987,
//     reset: 1704067200
//   }
// }

// Set custom request ID for tracing
const traced = await client.valuate(url, {
  requestId: 'order_12345_valuation',
});

Response Body Metadata

// Response body includes _metadata object
{
  "id": "val_abc123",
  "price_min": 1450,
  "price_max": 1850,
  "confidence": 95,
  
  "_metadata": {
    "request_id": "req_7f8g9h0i1j2k3l4m",
    "api_version": "2024-01-15",
    "processing_time_ms": 234,
    "model_version": "v3.2.1",
    "cache_status": "MISS",
    "region": "us-east-1",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Common Use Cases

Support Tickets

Include the X-Request-Id when contacting support. We can instantly trace your request through our entire system.

Performance Monitoring

Track X-Response-Time to monitor API latency. Alert on P95/P99 degradations in your observability stack.

Cache Optimization

Monitor X-Cache-Status to understand cache hit rates. Optimize request patterns for better performance.

Distributed Tracing

Pass your own X-Request-Id to correlate JustKalm API calls with your application's trace context.

Debug with Confidence

Rich metadata makes troubleshooting and optimization straightforward.

Debugging Guide API Reference