📦 Smart-Cache SEARCH - Backup API

Introduction

This API lets you manage backups of your underlying indices. You can:

Create a backup (snapshot) of an index
List all existing backups
Restore an index from a backup
Delete a backup

This API is ideal for automated workflows, scheduled backups, or manual data protection and recovery tasks.

The API supports authentication via JWT tokens.

Prerequisites

In order for this API to work as intended, a suitable repository must be created for the backup snapshots to be kept in. The set up of this repository is outside the scope of this document as it is dependent on the search solution (i.e. OpenSearch or Elasticsearch) and the type of storage solution (e.g. Amazon S3, Azure, shared file system). Please refer to the appropriate documentation linked below.

One important point to note is that the default repository name within the application is set to scs-snapshots-repo, so this name should be used for at least one repository created. Without this it will always be necessary to provide a repository name in the request.

🔐 Authentication

You must be authenticated to use the API.

Bearer Token (JWT): Include a standard Authorization: Bearer <your-jwt> header.

🛠️ Key Operations

✅ 1. Create a Backup

Endpoint: POST /backups/create

Purpose: Creates a backup (snapshot) of a specified index.

Parameters:

indexName: The name of index to back up. Optional: defaults to all configured indices.
repositoryName: The name of the repository to back up to. Optional: defaults to “scs-snapshots-repo”
snapshotPrefix: The name of the snapshot for the backup. Optional: defaults to “backup_snapshot”

Response: The details of the newly created backup.

Example:

curl -X POST https://telicent.core.domain/api/search/backups/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
    "indexName": "my_index",
    "repositoryName": "my_backup_repository",
    "snapshotPrefix": "my_backup_snapshot"
  }'

🗑️ 2. Delete a Backup

Endpoint: POST /backups/delete

Purpose: Deletes a backup snapshot from a repository.

Parameters:

repositoryName: The name of the repository to delete from. Optional: defaults to “scs-snapshots-repo”
snapshotName: The name of the snapshot to delete. Optional: defaults to “backup_snapshot”

Response: Confirmation of the deleted snapshot.

Example:

curl -X POST https://telicent.core.domain/api/search/backups/delete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{
      "repositoryName": "my_backup_repository",
      "snapshotName": "my_backup_snapshot_1748951775536"
    }'

📋 3. List Backups

Endpoint: GET /backups/list/{repositoryName}

Purpose: Returns a list of all snapshot backups in a given repository.

Parameters:

repositoryName: The name of the repository to list snapshots from.

Response: A list of the snapshots and their details within the repo, including but not limited to:

Description
Success state
Name
Start/End time

Example:

curl -X GET https://telicent.core.domain/api/search/backups/list/my_backup_repository \
  -H "Authorization: Bearer <jwt-token>"

♻️ 4. Restore a Backup

Endpoint: POST /backups/restore

Purpose:* Restores an index from a backup snapshot.

Parameters:

indexName: The name of the index to recover. Optional: defaults to all configured indices.
repositoryName: The name of the repository to restore from. Optional: defaults to “scs-snapshots-repo”
snapshotName: The name of the snapshot to restore from. Optional: defaults to “backup_snapshot”

Response: Confirms the success of the restoration.

Example:

curl -X POST https://telicent.core.domain/api/search/backups/restore \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
    "indexName": "my_index",
    "repositoryName": "my_backup_repository"
  }'

⚠️ Errors

If something goes wrong, you’ll get a response like this:

{
  "type": "CreateBackupFailed",
  "status": 400,
  "detail": "Snapshot already exists: backup_snapshot_1748951775536"
}

Error fields:

type: Type of error
status: HTTP status code
detail: Description of the error