Report issue candidates

Use POST /openapi/v1/issue-records when your local runtime detects behavior that may deserve an Issue. Recording a candidate does not mean an Issue is immediately created. The server stores the original record first. A background process then checks context, recovery state, and existing similar Issues before it creates a new Issue or adds an occurrence to an existing one.

Detection example

curl --request POST \
  --url https://api.lynxops.co/openapi/v1/issue-records \
  --header "X-API-Key: $LYNX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "sdkInstanceId": "python-worker-01",
    "clientRecordId": "record_01JZQ4A8C2",
    "recordKind": "DETECTION",
    "detectionType": "FIREWALL_BLOCK",
    "runId": "run_01JZQ3VY4K",
    "sessionId": "session_customer_42",
    "eventId": "evt_tool_04",
    "agentId": "support-agent",
    "policyId": "17",
    "promptVersionId": "c1821bc3-bf1e-46ef-b210-b9376a41cd0c",
    "detectedAt": 1784808000000,
    "payload": {
      "toolName": "delete_customer_data",
      "tools": ["search_customer", "delete_customer_data"],
      "riskSignals": ["destructive-action"]
    },
    "evidence": {
      "decision": "BLOCK"
    }
  }'

Fields

Field	Required	Description
`sdkInstanceId`	Yes	Stable client identifier. It should match the event `clientId`.
`clientRecordId`	Yes	Idempotency key for this record. Reuse it when retrying.
`recordKind`	Yes	`DETECTION` or `RECOVERY`.
`detectionType`	Yes	Stable detector category, such as `FIREWALL_BLOCK` or `RUN_ERROR`.
`runId`	No	Related external Run ID.
`sessionId`	No	Related external Session ID.
`eventId`	No	Related event idempotency key.
`agentId`	Yes	Stable external Agent ID.
`policyId`	No	Policy that produced the decision.
`promptVersionId`	No	Lynx prompt version UUID used by the run.
`detectedAt`	Yes	Unix time in milliseconds.
`payload`	No	Structured detector context.
`evidence`	No	Evidence supporting the candidate.

The request body limit is 256 KiB.

Supported detections

Detection type	When to send it	Recommended payload
`FIREWALL_BLOCK`	A local policy blocked an action.	`toolName`, `tools`, `riskSignals`, policy evidence
`FIREWALL_WARN`	A local policy allowed but flagged an action.	`toolName`, `tools`, `riskSignals`, policy evidence
`LOOP_DETECTED`	Repeated behavior crossed the local loop threshold.	`label`, `loopCount`, `argsHash`
`RUN_ERROR`	The root Run ended with an unhandled error.	Stable `errorCode`, `errorName`, and `errorSignature`
`RUN_FAILED`	An explicit technical or business outcome was failed.	`status`, `businessStatus`, and a stable reason code
`LLM_ERROR`	An instrumented LLM call failed.	`modelLabel`, `provider`, `model`, stable error metadata
`LLM_SLOW_RESPONSE`	Instrumented LLM calls repeatedly crossed a latency limit.	Model identity, `latencyMs`, `thresholdMs`, and consecutive count
`TOOL_ERROR`	An instrumented tool threw before returning a result.	`toolName`, `errorName`, stable `errorCode`, `argsHash`, `riskLevel`
`TOOL_TIMEOUT`	An asynchronous tool exceeded its configured deadline.	`toolName`, `timeoutMs`, `argsHash`, `riskLevel`
`PROMPT_REGRESSION`	A server-side prompt metric crossed a regression threshold.	Prompt version and metric evidence

For Run, LLM, and tool failures, use a stable provider or application error code when one is available. A raw error message may be included as masked evidence, but the server does not use it for grouping because messages often contain variable or sensitive values.

Accepted response

{
  "recordId": "7295695e-1960-43b5-9924-003d7163d0db",
  "status": "RECEIVED",
  "isNew": true
}

Possible statuses are RECEIVED, EVALUATING, DECIDED, and FAILED. isNew: false means the same sdkInstanceId and clientRecordId were already received. The response confirms durable receipt, not final Issue creation. Do not block a customer request while waiting for later evaluation.

Fingerprints and grouping

The client reports structured facts, not a grouping decision. The server derives its fingerprint from stable information such as detector type, policy, failed tool, tool set, reason code, and model context. It hashes the canonical value with SHA-256. Do not generate a random fingerprint per occurrence. Keep detector names and tool identifiers stable so equivalent situations can group consistently.

Recovery records

Send a new record with recordKind: "RECOVERY" when your runtime has evidence that the detected condition ended. Give the recovery its own clientRecordId, reuse the original detectionType, and include the same toolName or policy reference where applicable. Link the current Run or Session where possible. Recovery handling is asynchronous. A recovery record is evidence for server evaluation; it does not directly close an Issue.

Evidence can contain tool arguments, model output, or logs. Send only the minimum evidence needed to explain the detection, and mask secrets before enqueueing the record.

Getting started

TypeScript SDK

OpenAPI

Report issue candidates

Detection example

Fields

Supported detections

Accepted response

Fingerprints and grouping

Recovery records

​Detection example

​Fields

​Supported detections

​Accepted response

​Fingerprints and grouping

​Recovery records

Detection example

Fields

Supported detections

Accepted response

Fingerprints and grouping

Recovery records