Source: docs/integration/diagnostics.md

Capability-gap diagnostics

Forgium can expose unresolved capability diagnostics to the authenticated

account. These diagnostics help identify requests that the agent could not

resolve and decide which capability to implement next.

Diagnostics are strictly account-scoped. The API key determines the account;

the caller cannot select another account through the request.

Privacy modes

Configure the diagnostic response mode with:

PUT /v1/diagnostics/settings
Authorization: Bearer $FORGIUM_AGENT_API_KEY
Content-Type: application/json

{
  "diagnostic_message_mode": "metadata"
}

The supported modes are:

Mode	Behavior
`metadata`	Default. Returns category, correlation IDs, capability information, and timestamps; does not return message text.
`text`	Includes the original user message when it is still available under the platform message-retention policy.
`disabled`	Returns an empty account-facing report. Internal sanitized audit events and the separate conversation storage policy are unchanged.

Read the current setting with:

curl "$FORGIUM_AGENT_BASE_URL/v1/diagnostics/settings" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

Set metadata again to stop including message text in future diagnostic

responses, or disabled to stop the account-facing report entirely. This

setting controls the diagnostic report; it does not change the separate

conversation message-storage policy or internal audit retention.

List capability gaps

curl "$FORGIUM_AGENT_BASE_URL/v1/diagnostics/capability-gaps?limit=50" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

Example in metadata mode:

{
  "message_mode": "metadata",
  "has_more": false,
  "events": [
    {
      "id": "are_abc123",
      "agent_run_id": "run_abc123",
      "message_id": "msg_abc123",
      "category": "coverage_gap",
      "capability": null,
      "revision": null,
      "available_capabilities": ["list_consorcios", "list_unidades"],
      "created_at": "2026-09-02T14:34:51.000Z"
    }
  ]
}

When text mode is enabled, a retained message may be included:

{
  "message_mode": "text",
  "has_more": false,
  "events": [
    {
      "id": "are_abc123",
      "agent_run_id": "run_abc123",
      "message_id": "msg_abc123",
      "category": "coverage_gap",
      "capability": null,
      "revision": null,
      "available_capabilities": ["list_consorcios", "list_unidades"],
      "conversation_id": "conv_abc123",
      "message": "listar los propietarios de ese consorcio",
      "redacted": false,
      "truncated": false,
      "created_at": "2026-09-02T14:34:51.000Z"
    }
  ]
}

Interpreting categories

Category	Meaning	Suggested action
`coverage_gap`	The selection flow reported that no eligible capability could fulfill the request.	Review the message, then create or extend a read capability if the request is in scope.
`agent_dead_end`	The agent could not safely resolve the request.	Review the message and capability descriptions; it may be a routing problem or a missing capability.

These categories are operational hints, not verified classifications of user

intent. Confirm the need against the account's product scope before implementing

a capability.

Pagination and retention

Results are returned newest first. For the next page, pass the last event's

created_at and id as before and before_id:

GET /v1/diagnostics/capability-gaps?before=2026-09-02T14:34:51.000Z&before_id=are_abc123

Capability audit events follow the platform's 90-day audit-retention policy.

Message text follows the separate message-retention policy and may no longer

be available even while its diagnostic event remains.

The endpoint never returns messages, diagnostics, or capability data belonging

to another account.

When text mode is enabled, token-shaped values such as bearer tokens, API-key

assignments, and common key prefixes are redacted before the response. Do not

use diagnostic text as a secret store.