> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/console/knowledge/sync-and-versions.md).

# Sync & versions

How file updates reach agents through sync and knowledge versions.

A knowledge base uses files from its datasets. Update a file, then sync it to create a knowledge version. Agents use the latest completed version, so sync provides a controlled way to update their source knowledge.

Open a knowledge base and select **Datasets** to manage file updates and sync status.

### At a glance

| Goal                   | Action                                   | Result                                               |
| ---------------------- | ---------------------------------------- | ---------------------------------------------------- |
| Update knowledge       | Upload a new file version, then sync it. | Agents use the updated content after sync completes. |
| Review changes         | Open the knowledge version menu.         | See versions and the change that created each one.   |
| Keep a dataset current | Enable auto sync.                        | Eligible new files sync automatically.               |
| Resolve an issue       | Filter for items needing attention.      | Find failed and stale files.                         |

### How updates reach agents

**File → dataset → sync → knowledge version → agents**

A dataset holds source files. Adding or replacing a file does not update a knowledge base immediately. The file remains **Ready to sync** until you sync it.

{% hint style="info" %}
**A completed sync is live.** There is no draft or publish stage. Validate important updates in [Try Knowledge](/console/knowledge/try-knowledge.md), then compare answers with the previous version when needed.
{% endhint %}

{% columns %}
{% column %}

#### Before sync

* A new file version remains outside the knowledge base.
* Agents continue using the previous knowledge version.
* You can review the replacement before it becomes active.
  {% endcolumn %}

{% column %}

#### After sync

* Each synced file creates a knowledge version.
* Agents use the latest completed version.
* The file status changes to **Synced**.
  {% endcolumn %}
  {% endcolumns %}

### Knowledge and file versions

Knowledge versions record how the knowledge base changed. The version history shows the latest version first, including:

* The file that a sync added.
* A dataset attachment.
* The initial knowledge-base version.

Each completed file sync creates a separate knowledge version. Version numbers only increase. Earlier versions remain available for queries in [Try Knowledge](/console/knowledge/try-knowledge.md), but you cannot make an earlier version current.

To update a file, select **⋮** → **Upload new version**, then choose the replacement. The file retains its name and receives the next file version number. Use **Version history** to review earlier file versions.

{% hint style="warning" %}
Cloud-source changes do not sync automatically. When a source changes in Google Drive, OneDrive, or SharePoint, upload the new version before you sync it.
{% endhint %}

### Sync files

Choose the scope that matches your change:

{% tabs %}
{% tab title="All ready files" %}
Select **Sync ready files** to sync every ready file across the knowledge base. This option is unavailable when no files are ready.
{% endtab %}

{% tab title="One dataset" %}
Select **Sync N ready** on a dataset to sync only that dataset's ready files. Use **Re-sync all** when no files are ready but the dataset needs syncing again.
{% endtab %}

{% tab title="Dataset actions" %}
Use the dataset menu for targeted actions:

| Action                          | Use it when                                           |
| ------------------------------- | ----------------------------------------------------- |
| **Sync all preprocessed files** | All processed files in the dataset should be current. |
| **Force re-sync everything**    | You need to rebuild this dataset's contribution.      |
| **Retry failed files only**     | Only failed files need another attempt.               |
| **Upload files to dataset**     | You have new source material.                         |
| **Detach dataset**              | This knowledge base should no longer use the dataset. |
| {% endtab %}                    |                                                       |
| {% endtabs %}                   |                                                       |

{% hint style="warning" %}
**Force re-sync everything** processes every file again. Each synced file creates a version. Use **Retry failed files only** when failures are isolated.
{% endhint %}

#### Auto sync

Enable **Auto sync** from the dataset menu when new files should sync without manual action. Use manual sync for content that requires review before agents use it, such as policies or rate information.

### Understand statuses

Dataset status shows whether its files are available to the knowledge base. The status summary tracks attached files, fully synced datasets, ready files, files in progress, and failed files.

| Dataset status       | Meaning                                               |
| -------------------- | ----------------------------------------------------- |
| **Not synced**       | No files from this dataset are in the knowledge base. |
| **Partially synced** | Some files are synced and others are not.             |
| **Auto sync**        | New eligible files sync automatically.                |

Each file has independent discovery and sync statuses.

{% columns %}
{% column %}

#### Discovery status

| Status                      | Meaning                 |
| --------------------------- | ----------------------- |
| **Discoverable**            | Indexed and searchable. |
| **Preparing for discovery** | Being indexed.          |
| {% endcolumn %}             |                         |

{% column %}

#### Sync status

| Status                    | Action                        |
| ------------------------- | ----------------------------- |
| **Ready to sync**         | Sync the file.                |
| **Syncing**               | Wait for completion.          |
| **Synced**                | No action is needed.          |
| **New version available** | Sync the newer file version.  |
| **Sync failed**           | Retry the file.               |
| **Not eligible**          | Wait for discovery to finish. |
| {% endcolumn %}           |                               |
| {% endcolumns %}          |                               |

A file can be **Discoverable** and **Ready to sync**. It is searchable as a source, but agents do not yet answer from it.

### Resolve items needing attention

Items need attention when a file failed or a newer file version is available. Select **Review** to see those items, or filter by **All**, **Needs attention**, **Ready to sync**, **Processing**, or **Synced**. Search by dataset or file name to find a specific item.

For failed processing, retry the file after addressing the source issue. See [When processing fails](/console/knowledge.md#when-processing-fails) for common causes and retry guidance.

{% hint style="info" %}
One dataset can support several knowledge bases. Syncing it in one knowledge base does not update the others. Each knowledge base maintains its own sync statuses and knowledge versions.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Knowledge</strong></td><td>Create knowledge bases and work with them.</td><td><a href="/console/knowledge.md">Knowledge</a></td></tr><tr><td><strong>Datasets</strong></td><td>Add files from uploads, cloud drives or a website.</td><td><a href="/console/knowledge/datasets.md">Datasets</a></td></tr><tr><td><strong>Try Knowledge</strong></td><td>Query any version and see the chunks behind each answer.</td><td><a href="/console/knowledge/try-knowledge.md">Try Knowledge</a></td></tr><tr><td><strong>Knowledge FAQs</strong></td><td>Short answers about sync, versions and files.</td><td><a href="/console/knowledge/faqs.md">Knowledge: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.uptiq.ai/console/knowledge/sync-and-versions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.