How to Restore an Item

This guide explains the algorithm behind restoring an item by selecting a point in time. It walks through every stage in execution order and shows the exact API calls at each step.

Overview

The algorithm consists of the following stages:

1. Search — find the target item using the bsearch API.
2. Snapshot lookup — resolve the desired timestamp to a concrete snapshot ID.
3. Submit — POST a restore job for the item and collect the result.
4. Verify (optional) — confirm the job was accepted and track its progress.

Stage 1 — Search for the Item

See the Search Backup page for details.

Use the bsearch endpoint to locate the target item. Use filterOr=AND:!sys; to exclude system items from the results.

Set the following query parameters:

Code
curl -s -u "{username}:{password}" \
  -H "Accept: application/vnd.keepit.v4+xml" \
  "https://{baseUrl}/users/{accountId}/bsearch\
        ?apiVersion=2\
        &device={connectorId}\
        &pathRoot={pathRoot}\
        &filterOr=AND:!sys;\
        &sortTerms=folder,title,id\
        &count=500\
        &startIndex=0"

Add &searchTerms={searchTerms} to narrow results by keyword (optional). Omit it to return all items under the given pathRoot.

Optionally, you can paginate through the results: request one page of count items at a time, increasing startIndex by count for each next page, until a page returns fewer than count items. For example, with count=500, request startIndex=0, then 500, then 1000, and so on.

pathRoot by item type

The pathRoot value depends on the item type being restored.

Email:

Code
/Users/{userIdentity}/Outlook/{folderName}

Omit /{folderName} to search the entire Outlook mailbox. Otherwise, append the folder name to narrow the search (e.g. /Users/{userIdentity}/Outlook/Inbox).

OneDrive:

Code
/Users/{userIdentity}/{pathFromRoot}

If the search returns zero results, retry with the alternate OneDrive path:

• If pathFromRoot starts with OneDrive: /Users/{userIdentity}/OneDriveSP/DocLibs/Documents/Content
• Otherwise: /Users/{userIdentity}/OneDrive

SharePoint:

Code
/SharePoint/{encodedSiteUrl}

Omit /{encodedSiteUrl} to search across all SharePoint sites. To target one site, set encodedSiteUrl to the escape-masked site URL. For example, https://m365x47291058.sharepoint.com/sites/allcompany becomes /SharePoint/https-c-s-sm365x47291058.sharepoint.com-ssites-sallcompany.

Groups & Teams:

Code
/Groups/{groupId}

Omit /{groupId} to search across all groups. To target one group, set groupId to the escape-masked group GUID. For example, /Groups/f3a1b2c4--d7e8--4f91--a023--b6c5d4e3f2a1.

Path segment encoding

Special characters inside individual path segments must be escaped before building pathRoot. See Escape Masking for the full rules and examples.

Code
GET https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/bsearch?apiVersion=2&device=ou1ab2-3cde4-fg5hi6&pathRoot=/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p/Outlook/Inbox&filterOr=AND:!sys;&sortTerms=folder,title,id&count=500&startIndex=0

Code
<feed>
  <opensearch:totalResults>12</opensearch:totalResults>
  <entry>
    <id>kng://{connectorId}/Users/{user}/Outlook/Inbox/...</id>
    <title>Q1 budget review</title>
    <updated>2026-04-11T22:51:48Z</updated>
  </entry>
  …
</feed>

Code
  <entry>
    <id>kng://{connectorId}/Users/{user}/Outlook/Inbox/...</id>
    <title>Q4 budget review</title>
    <updated>2025-12-15T21:11:48Z</updated>
    <deleted/>
  </entry>

[!TIP] <updated> is an ISO 8601 UTC timestamp identifying when the item was last seen in a snapshot — you will need this value in Stage 2. Identify the target <entry> from the results before proceeding.

Stage 2 — Resolve Snapshot ID

See the [Retrieve Snapshot History Range] page for details.

For the target item you need the snapshot ID that corresponds to the desired point in time. Query the snapshot history range endpoint backwards from the item's <updated> timestamp.

Send the following <range> body:

Code
curl -s -u "{username}:{password}" \
  -X PUT \
  -H "Content-Type: application/xml" \
  -H "Accept: application/vnd.keepit.v4+xml" \
  -d '<range>
        <start>{updated}</start>
        <span>P30D</span>
        <count>1</count>
        <reverse/>
    </range>' \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/history/range"

Code
PUT https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/history/range

Code
<range>
  <start>2026-04-11T22:51:48Z</start>
  <span>P30D</span>
  <count>1</count>
  <reverse/>
</range>

Code
<history>
  <backup>
    <tstamp>{ISO 8601 timestamp}</tstamp>
    <root>{snapshotId}</root>
    <type>{c|p}</type>
    <size>{bytes}</size>
    <account>{accountId}</account>
  </backup>
</history>

Stage 3 — Build and Submit the Restore Job

See the Create Device Job page for details.

Construct the XML job definition and POST it to the API.

Build the following <job> body:

XML job definition

Code
<job>
  <description>[srestore] Restore of an item</description>
  <type>srestore</type>
  <immediate/>
  <priority>1</priority>
  <commands>
    <restore>
      <RestoreConfig>
        <SnapshotId>{snapshotId}</SnapshotId>
        <Rules>
          <Mode>
            <FolderRestoreMode>DeltaAppend</FolderRestoreMode>
            <FileConflictResolutionMode>Restore</FileConflictResolutionMode>
            <Method>InPlace</Method>
          </Mode>
          <RestorePaths>
            <Path>{path}</Path>
          </RestorePaths>
        </Rules>
      </RestoreConfig>
    </restore>
  </commands>
</job>

Path value inside <Path>:

To get the <Path> value for the restore job, strip the kng://{connectorId} prefix, leaving just /{path}, then XML-escape the result as defined by the XML specification (encode &, <, >, ", and ' as their XML entities).

For example, given the <id> returned by bsearch:

Code
kng://ab1cd2-3efgh4-ij5klm/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p

The <Path> value is:

Code
/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p

Code
curl -s -u "{username}:{password}" \
  -X POST \
  -H "Content-Type: application/xml" \
  -H "Accept: application/vnd.keepit.v4+xml" \
  -d '<job>...</job>' \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/jobs/"

Code
POST https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/jobs/

Code
<job>
  <description>[srestore] Restore of an item</description>
  <type>srestore</type>
  <immediate/>
  <priority>1</priority>
  <commands>
    <restore>
      <RestoreConfig>
        <SnapshotId>c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4</SnapshotId>
        <Rules>
          <Mode>
            <FolderRestoreMode>DeltaAppend</FolderRestoreMode>
            <FileConflictResolutionMode>Restore</FileConflictResolutionMode>
            <Method>InPlace</Method>
          </Mode>
          <RestorePaths>
            <Path>/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p</Path>
          </RestorePaths>
        </Rules>
      </RestoreConfig>
    </restore>
  </commands>
</job>

Stage 4 — Verify the Restore Job (optional)

See the List Device Jobs page for details.

To confirm the job was accepted and track its progress, query the jobs endpoint:

Code
curl -s -u "{username}:{password}" \
  -H "Accept: application/vnd.keepit.v4+xml" \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/jobs"

Code
GET https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/jobs

Code
<jobs>
    <job>
        <guid>9ab1c2-de3fg4-hi5jk6-lm7nop</guid>
        <description>[srestore] Restore of an item</description>
        <type>srestore</type>
        <priority>1</priority>
        <active>false</active>
        <start>2026-04-12T08:30:00Z</start>
        <scheduled>2026-04-12T08:30:00Z</scheduled>
        <dispatched>2026-04-12T08:30:05Z</dispatched>
        <started>2026-04-12T08:30:05Z</started>
        <succeeded>2026-04-12T08:30:42Z</succeeded>
        <progress>1.0</progress>
    </job>
</jobs>