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

# conflicts

> Conflict management: list a dataset's fact conflicts and record which competing fact you accept

# Conflict management

Conflict review in [`improve()`](https://docs.cognee.ai/python-api/improve) stores one `FactConflict` per disputed attribute of an entity. When the review cannot decide which fact holds, for example because two sources disagree on something that never changes, the conflict stays `unresolved`. These functions let you inspect the stored conflicts and settle one yourself. Both are async, take the dataset **id** rather than its name, and are available since Cognee 1.6.6.

```python theme={null}
import cognee

conflicts = await cognee.list_conflicts(dataset_id, status="unresolved")
await cognee.resolve_conflict(
    conflicts[0].id,
    dataset_id=dataset_id,
    selected_fact_id=conflicts[0].facts[0].id,
)
```

For a walkthrough, see [Resolve Conflicting Facts](https://docs.cognee.ai/guides/resolve-conflicts.md).

## Methods

### list\_conflicts()

```python theme={null}
await cognee.list_conflicts(
    dataset_id: UUID,
    *,
    status: Literal["resolved", "unresolved"] | None = None,
    user: Optional[User] = None,
) -> list[ConflictDetail]
```

Returns a dataset's conflicts sorted by id, each with its competing facts (their ids, text, status, and source evidence) and any earlier decision. Returns an empty list when nothing matches. Raises `PermissionDeniedError` (403) if you lack read access to the dataset or it does not exist, and `CogneeValidationError` (422) for any other `status` value.

| Parameter | Type | Default | Notes |
| - | - | - | - |
| `dataset_id` | `UUID` | required | The dataset whose conflicts to list. Requires read permission. |
| `status` | `"resolved" \| "unresolved" \| None` | `None` | Return only conflicts with this status. `None` returns all of them. |
| `user` | `Optional[User]` | `None` | If omitted, Cognee resolves the default user. Not used in remote mode. |

#### Remote mode (`serve()`)

After [`cognee.serve()`](https://docs.cognee.ai/python-api/serve), the call runs on the connected instance through `GET /api/v1/conflicts`. The API key identifies the caller, so `user` is ignored, and an HTTP error is raised as `RuntimeError` carrying the status code.

### resolve\_conflict()

```python theme={null}
await cognee.resolve_conflict(
    conflict_id: UUID,
    *,
    dataset_id: UUID,
    selected_fact_id: UUID,
    reason: Optional[str] = None,
    user: Optional[User] = None,
) -> ConflictDetail
```

Accepts one of a conflict's facts and returns the updated conflict. The conflict becomes `resolved` with `resolution_source="user"`, the selected fact is marked `current`, and the others are marked `superseded`. Rejected facts are not deleted: they stay in the graph as evidence, while graph-completion and hybrid search leave them out of their context and state the accepted fact instead.

A later automatic review keeps your decision for as long as the selected fact exists. Repeating the same choice changes nothing. If a review has since added a fact to the conflict, the repeated choice rejects that fact as well. Choosing a different fact replaces the earlier decision.

Raises `PermissionDeniedError` (403) if you lack write access to the dataset or it does not exist, `EntityNotFoundError` (404) if the dataset holds no conflict with this id, and `CogneeValidationError` (422) if `selected_fact_id` is not one of the conflict's facts.

| Parameter | Type | Default | Notes |
| - | - | - | - |
| `conflict_id` | `UUID` | required | The conflict to settle, from `ConflictDetail.id`. |
| `dataset_id` | `UUID` | required | The dataset that holds the conflict. Requires write permission. |
| `selected_fact_id` | `UUID` | required | The fact to accept: the `id` of one of the conflict's `facts`. |
| `reason` | `Optional[str]` | `None` | An optional explanation, stored as `resolution_reason`. |
| `user` | `Optional[User]` | `None` | If omitted, Cognee resolves the default user. Recorded as `resolved_by`. Not used in remote mode. |

#### Remote mode (`serve()`)

After [`cognee.serve()`](https://docs.cognee.ai/python-api/serve), the call runs on the connected instance through `POST /api/v1/conflicts/{conflict_id}/resolve`. The API key identifies the caller, so `user` is ignored, and an HTTP error is raised as `RuntimeError` carrying the status code.

## Return types

Both models are exported from `cognee`. Over HTTP their keys are camelCase (`datasetId`, `selectedFactId`, …).

### ConflictDetail

| Field | Type | Notes |
| - | - | - |
| `id` | `UUID` | The conflict id to pass to `resolve_conflict()`. |
| `dataset_id` | `UUID` | The dataset that holds the conflict. |
| `about_id` | `str` | The entity the conflict is about. |
| `attribute` | `str` | The disputed attribute. |
| `kind` | `"time_varying" \| "fixed"` | Whether the answer can change over time. |
| `status` | `"resolved" \| "unresolved"` | Whether a fact has been accepted. |
| `text` | `str` | A one-sentence summary of the conflict. |
| `facts` | `list[ConflictFact]` | The competing facts. |
| `resolution_source` | `"review" \| "user"` | Who settled it: the automatic review or a `resolve_conflict()` call. |
| `selected_fact_id`, `selected_fact` | `Optional[UUID]`, `Optional[str]` | The accepted fact, after a user decision. |
| `resolved_by`, `resolved_at` | `Optional[UUID]`, `Optional[str]` | Who made the user decision, and when (ISO 8601). |
| `resolution_reason` | `Optional[str]` | The `reason` passed to `resolve_conflict()`. |
| `write_pending` | `bool` | `True` while a decision is still being finalized. |

### ConflictFact

| Field | Type | Notes |
| - | - | - |
| `id` | `UUID` | The fact id to pass as `selected_fact_id`. |
| `text` | `str` | The fact as a sentence. |
| `source_id`, `target_id`, `relationship` | `str` | The graph edge that states the fact. |
| `status` | `str` | The fact's status within this conflict: `current`, `superseded`, or `conflicting`. |
| `sources` | `list[dict]` | The source evidence that states the fact. |

## HTTP API

The same operations are available over HTTP. Request bodies accept camelCase or snake\_case keys.

| Method | Path | Body or query |
| - | - | - |
| `GET` | `/api/v1/conflicts` | Query: `dataset_id` (required), `status` (optional). Requires read permission. |
| `POST` | `/api/v1/conflicts/{conflict_id}/resolve` | Body: `dataset_id`, `selected_fact_id`, optional `reason`. Requires write permission. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.