Load runtime config

Use GET /openapi/v1/runtime-config when your integration starts, then refresh it on a configurable interval. The endpoint requires both config:read and policies:read.

curl --request GET \
  --url https://api.lynxops.co/openapi/v1/runtime-config \
  --header "X-API-Key: $LYNX_API_KEY"

Response

{
  "revision": "a40b9dbd7f6d5c67c8f0b2c2e6d40f6cd26e13b9f36cc51af0a89b69f7ab07f1",
  "prompts": [
    {
      "promptId": "72adbb57-96ad-4d3d-a2dc-8faf071673e5",
      "name": "support-agent",
      "versionId": "c1821bc3-bf1e-46ef-b210-b9376a41cd0c",
      "version": "v3",
      "content": "You are a support agent.",
      "contentHash": "b11c0c8f2dbe3be223af31f44a9faca0f8f5d4ff2595428815ed4de6c56e4f35"
    }
  ],
  "policies": [
    {
      "policyId": "17",
      "name": "Block destructive tools",
      "description": null,
      "version": "v2",
      "condition": "tool.riskLevel == 'CRITICAL'",
      "severity": "CRITICAL",
      "action": "BLOCK"
    }
  ]
}

contentHash is a lowercase SHA-256 hex digest of the prompt content. Verify it before replacing a cached prompt.

Conditional refresh

The response includes an ETag based on revision. Save it and send it on the next refresh:

If-None-Match: "a40b9dbd7f6d5c67c8f0b2c2e6d40f6cd26e13b9f36cc51af0a89b69f7ab07f1"

A 304 Not Modified response has no body. Keep using the current cache and update its last-checked time.

Cache behavior

Your implementation should:

Load a previously validated cache from local storage.
Request the current configuration during startup without blocking normal event delivery.
Replace the cache atomically only after the complete response validates.
Refresh on a configurable interval with jitter.
Keep the last known good configuration when the API is unavailable.
expose prompts by stable ID or name and return their versionId with the content.

TypeScript SDK `.lynxconf` cache

The TypeScript SDK can persist the last validated bundle as a compact binary .lynxconf file:

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  runtimeConfig: {
    enabled: true,
    refreshIntervalMs: 60_000,
    cache: {
      enabled: true,
      path: "./.lynxconf",
    },
  },
});

Persistent caching is disabled by default. When path is omitted, the SDK uses the operating system’s user cache directory. You can also supply cache.storage to use another byte store. The file contains a versioned compact JSON payload compressed with gzip. It has an LXCF signature and a SHA-256 checksum. The SDK writes only after a new revision passes full validation, skips writes for unchanged revisions and 304 responses, and uses a temporary file plus atomic rename. shutdown() waits for a pending cache write. At startup, a valid cache is made available before background server revalidation finishes. Invalid, mismatched, or corrupt cache files are ignored and removed. The API key is never written to .lynxconf. Attach versionId as promptVersionId to relevant run events and issue records. This connects behavior to the exact Lynx-managed prompt version. Policies are designed for local evaluation before a tool call. Do not call the API for every tool execution.

Prompt content can contain confidential instructions. Protect the local cache with the same access controls as application configuration, and do not write prompt content or API keys to diagnostic logs.

Getting started

TypeScript SDK

OpenAPI

Load runtime config

Response

Conditional refresh

Cache behavior

TypeScript SDK `.lynxconf` cache

​Response

​Conditional refresh

​Cache behavior

​TypeScript SDK .lynxconf cache

Response

Conditional refresh

Cache behavior

TypeScript SDK `.lynxconf` cache