> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hunt Pivot Responses

> Interpret ranked hunt pivot recommendations for subject-led and observation-led investigations.

`/v2/hunt-pivots` returns ranked investigative actions for threat-hunting agents. Use it when an agent needs to decide what to investigate next, why it matters, and what telemetry fields to collect.

Use `/v2/relationships` instead when you only need related actors, campaigns, malware, sectors, indicators, or techniques for a resolved subject.

## Response Envelope

`/v2/hunt-pivots` returns:

| Field                  | Meaning                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `mode`                 | Request mode: `subject_led` or `observation_led`.                                          |
| `resolution_status`    | Whether Kyberis resolved the subject or proceeded from an unresolved observation.          |
| `subject`              | Resolved or submitted subject context when available.                                      |
| `likely_attack_chains` | ATT\&CK-aligned hypotheses that may explain the subject or observation.                    |
| `recommended_pivots`   | Ranked hunt actions for the customer agent to execute.                                     |
| `next_decision`        | Recommendation for whether to continue, collect more context, escalate, suppress, or stop. |
| `caveats`              | Top-level limitations and assumptions for the response.                                    |
| `metadata`             | Request and generation metadata, including degradation or implementation details.          |

## Modes

| Mode              | Use when                                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `subject_led`     | You have a resolved Kyberis subject such as an actor, CVE, malware family, campaign, technique, or IOC.              |
| `observation_led` | You have weak telemetry, unresolved observables, or an anomaly that does not resolve to a canonical Kyberis subject. |

Observation-led requests should still return non-empty pivots when entity resolution is unavailable or the observable is unresolved.

## Recommended Pivots

Each item in `recommended_pivots` is an action for the customer agent to execute against local SIEM, EDR, cloud, identity, or asset telemetry.

| Field              | Meaning                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `pivot_type`       | Hunt category such as `network_pivot`, `process_pivot`, `technique_hunt`, `ioc_expansion`, or `asset_exposure_check`. |
| `priority`         | Relative urgency for this pivot.                                                                                      |
| `question`         | Investigation question the pivot should answer.                                                                       |
| `query_intent`     | Vendor-neutral search intent for the customer telemetry system.                                                       |
| `why`              | Rationale for the pivot.                                                                                              |
| `confidence`       | Confidence in the pivot recommendation, not proof of compromise.                                                      |
| `required_fields`  | Telemetry fields the customer agent should collect.                                                                   |
| `related_entities` | Optional Kyberis relationship context used to support the recommendation.                                             |
| `evidence_refs`    | Optional evidence references that support the recommendation.                                                         |
| `caveats`          | Limits or assumptions for the specific pivot.                                                                         |

## Attack Chains

`likely_attack_chains` contains ATT\&CK-aligned hypotheses. Treat these as hypotheses until customer-local telemetry confirms them.

## Next Decision

`next_decision` summarizes whether the agent should continue hunting, collect more context, escalate, or suppress. Preserve the recommendation and reason in agent output so analysts can see why the workflow continued.