Upgrade the C# API client to version 7

The latest major version of the Algolia.Search package is version 7. This page helps you upgrade from version 6 and explains the breaking changes you need to address. Algolia generates the version 7 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural change is the removal of the InitIndex pattern: all methods are now on the client instance directly, with indexName as a parameter. For the full list of changes, see the C# changelog.

Update your dependencies

Update the Algolia.Search package to version 7:

dotnet add package Algolia.Search --version "7.*"

Version 7 replaces the Newtonsoft.Json dependency with System.Text.Json. If your project relies on Newtonsoft-specific attributes or converters, see Update the serialization library for migration guidance.

Update imports

The package name remains Algolia.Search, but several model types have been renamed. For example, the Query class no longer exists. It’s replaced by SearchParams and SearchParamsObject.

// version 6
using Algolia.Search.Clients;
using Algolia.Search.Models.Search;

// version 7
using Algolia.Search.Clients;
using Algolia.Search.Models.Search;

The SearchClient class stays in the same namespace. As you update your code, your IDE will flag missing types and suggest the correct using directives for the new model classes.

Update client initialization

Client creation is unchanged. The constructor still accepts your application ID and API key:

// version 6
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// version 7
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

The other major change concerns what follows initialization: InitIndex no longer exists.

Synchronous and asynchronous methods

Version 7 includes both synchronous and asynchronous variants for every API method. Asynchronous methods have an Async suffix and return a Task<T>. Synchronous methods keep the base name.

// Asynchronous (recommended)
var results = await client.SearchSingleIndexAsync<Hit>("ALGOLIA_INDEX_NAME", searchParams);

// Synchronous
var results = client.SearchSingleIndex<Hit>("ALGOLIA_INDEX_NAME", searchParams);

The code examples in this guide use the asynchronous variants. If you prefer synchronous calls, drop the Async suffix and the await keyword.

Remove `InitIndex`

This is the most significant change when upgrading. Version 6 relied on an index object with methods called on it. In version 7, all methods belong to the client instance, with indexName as a parameter.

// version 6
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
var results = index.Search<Contact>(new Query("QUERY"));

// version 7
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
var results = await client.SearchSingleIndexAsync<Hit>(
    "ALGOLIA_INDEX_NAME",
    new SearchParams(new SearchParamsObject { Query = "QUERY" })
);

If you have many files to update, search your codebase for InitIndex or .InitIndex( to find every place that needs changing.

Update search calls

Search a single index

The index.Search() method is now client.SearchSingleIndexAsync(). Pass the index name and search parameters directly:

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
var results = await index.SearchAsync<Contact>(new Query("QUERY")
{
    FacetFilters = new List<string> { "category:Book" }
});

// version 7
var results = await client.SearchSingleIndexAsync<Hit>(
    "ALGOLIA_INDEX_NAME",
    new SearchParams(new SearchParamsObject
    {
        Query = "QUERY",
        FacetFilters = new FacetFilters(new List<string> { "category:Book" })
    })
);

Search multiple indices

The client.MultipleQueries() method is now client.SearchAsync(). Each request in the collection requires an IndexName:

// version 6
var results = await client.MultipleQueriesAsync<Hit>(
    new List<MultipleQueriesQuery>
    {
        new MultipleQueriesQuery { IndexName = "INDEX_1", Params = new Query("QUERY") },
        new MultipleQueriesQuery { IndexName = "INDEX_2", Params = new Query("QUERY") }
    }
);

// version 7
var results = await client.SearchAsync<Hit>(
    new SearchMethodParams
    {
        Requests = new List<SearchQuery>
        {
            new SearchQuery(new SearchForHits { IndexName = "INDEX_1", Query = "QUERY" }),
            new SearchQuery(new SearchForHits { IndexName = "INDEX_2", Query = "QUERY" })
        }
    }
);

The index.SearchForFacetValues() method becomes client.SearchForFacetValuesAsync() with an indexName parameter:

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
var results = await index.SearchForFacetValueAsync("category", "book");

// version 7
var results = await client.SearchForFacetValuesAsync(
    "ALGOLIA_INDEX_NAME",
    "category",
    new SearchForFacetValuesRequest { FacetQuery = "book" }
);

Update indexing operations

In version 7, indexing methods are on the client instead of the index object, with indexName as a parameter.

Add or replace records

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
await index.SaveObjectAsync(new { ObjectID = "1", Name = "Record" });
await index.SaveObjectsAsync(new List<object> { new { ObjectID = "1", Name = "Record" } });

// version 7
await client.SaveObjectAsync("ALGOLIA_INDEX_NAME", new { ObjectID = "1", Name = "Record" });
// SaveObjectsAsync works the same way:
// (note: pass a list of objects for the batch version)
await client.SaveObjectsAsync(
    "ALGOLIA_INDEX_NAME",
    new List<object> { new { ObjectID = "1", Name = "Record" } }
);

Partially update records

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
await index.PartialUpdateObjectAsync(new { ObjectID = "1", Name = "Updated" });

// version 7
await client.PartialUpdateObjectAsync(
    "ALGOLIA_INDEX_NAME",
    "1",
    new { Name = "Updated" }
);

Delete records

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
await index.DeleteObjectAsync("1");

// version 7
await client.DeleteObjectAsync("ALGOLIA_INDEX_NAME", "1");

Update settings, synonyms, and rules

Get and set settings

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
var settings = await index.GetSettingsAsync();
await index.SetSettingsAsync(new IndexSettings
{
    SearchableAttributes = new List<string> { "title", "author" }
});

// version 7
var settings = await client.GetSettingsAsync("ALGOLIA_INDEX_NAME");
await client.SetSettingsAsync(
    "ALGOLIA_INDEX_NAME",
    new IndexSettings
    {
        SearchableAttributes = new List<string> { "title", "author" }
    }
);

Save synonyms and rules

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
await index.SaveSynonymsAsync(synonyms);
await index.SaveRulesAsync(rules);

// version 7
await client.SaveSynonymsAsync(
    "ALGOLIA_INDEX_NAME",
    synonyms
);
await client.SaveRulesAsync(
    "ALGOLIA_INDEX_NAME",
    rules
);

In version 6, index.ReplaceAllRules() and index.ReplaceAllSynonyms() replaced all rules or synonyms. In version 7, use client.SaveRulesAsync() or client.SaveSynonymsAsync() with the clearExistingRules or clearExistingSynonyms parameter set to true.

Update index management

The CopyIndex, MoveIndex, CopyRules, CopySynonyms, and CopySettings methods are all replaced by OperationIndexAsync.

Copy an index

// version 6
await client.CopyIndexAsync("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 7
await client.OperationIndexAsync(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams
    {
        Operation = Enum.Parse<OperationType>("Copy"),
        Destination = "DESTINATION_INDEX_NAME"
    }
);

Move (rename) an index

// version 6
await client.MoveIndexAsync("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 7
await client.OperationIndexAsync(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams
    {
        Operation = Enum.Parse<OperationType>("Move"),
        Destination = "DESTINATION_INDEX_NAME"
    }
);

Copy only rules or settings

In version 7, use the Scope parameter to limit the operation to specific data:

// version 7 -- copy only rules and settings from one index to another
await client.OperationIndexAsync(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams
    {
        Operation = Enum.Parse<OperationType>("Copy"),
        Destination = "DESTINATION_INDEX_NAME",
        Scope = new List<ScopeType> { ScopeType.Rules, ScopeType.Settings }
    }
);

Update task handling

Version 6 supported chaining .Wait() on operations. Version 7 replaces this pattern with dedicated wait helpers.

// version 6
var index = client.InitIndex("ALGOLIA_INDEX_NAME");
index.SaveObjects(records).Wait();

// version 7
var response = await client.SaveObjectsAsync("ALGOLIA_INDEX_NAME", records);
await client.WaitForTaskAsync("ALGOLIA_INDEX_NAME", response.TaskID);

Version 7 includes three wait helpers:

WaitForTask: wait until indexing operations are done.
WaitForAppTask: wait for application-level tasks.
WaitForApiKey: wait for API key operations.

Update the serialization library

The Algolia.Search package no longer depends on Newtonsoft.Json for request serialization and response deserialization. Version 7 uses .NET’s official System.Text.Json package instead. This is a significant change if your project relies on Newtonsoft.Json attributes (such as [JsonProperty]) for custom serialization of your Algolia records. If you were using the Newtonsoft.Json package for custom serialization, see Migrate from Newtonsoft.Json to System.Text.Json in Microsoft’s documentation.

Common attribute replacements when migrating from Newtonsoft.Json:

[JsonProperty("name")] becomes [JsonPropertyName("name")]
[JsonIgnore] keeps the same name but moves to the System.Text.Json.Serialization namespace
Custom JsonConverter implementations need rewriting for System.Text.Json

Update enumeration serialization

To keep the serialization of enumeration types consistent with previous versions of the .NET API client, they’re serialized as int by default. To serialize enumeration types as strings, use the JsonStringEnumConverter attribute from System.Text.Json.Serialization:

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum MyEnum
{
    MyValue1,
    MyValue2
}

public class MyModel
{
    public MyEnum MyProperty { get; set; }
}

await client.SaveObjectAsync("ALGOLIA_INDEX_NAME", new MyModel { MyProperty = MyEnum.MyValue2 });

With this attribute, MyProperty serializes as the string "MyValue2" instead of the integer 1.

Method changes reference

The following tables list all method names that changed between version 6 and version 7.

Search API client

Version 6 (legacy)		Version 7 (current)
`client.AddApiKey`	→	`client.AddApiKey`
`client.AddApiKey.Wait`	→	`client.WaitForApiKey`
`DictionaryClient.ClearDictionaryEntries`	→	`client.BatchDictionaryEntries`
`client.CopyIndex`	→	`client.OperationIndex`
`client.CopyRules`	→	`client.OperationIndex`
`client.CopySynonyms`	→	`client.OperationIndex`
`client.DeleteApiKey`	→	`client.DeleteApiKey`
`DictionaryClient.DeleteDictionaryEntries`	→	`client.BatchDictionaryEntries`
`client.GenerateSecuredApiKey`	→	`client.GenerateSecuredApiKey`
`client.GetApiKey`	→	`client.GetApiKey`
`client.GetSecuredApiKeyRemainingValidity`	→	`client.GetSecuredApiKeyRemainingValidity`
`client.ListApiKeys`	→	`client.ListApiKeys`
`client.ListIndices`	→	`client.ListIndices`
`client.MoveIndex`	→	`client.OperationIndex`
`client.MultipleBatch`	→	`client.MultipleBatch`
`client.MultipleQueries`	→	`client.Search`
`DictionaryClient.ReplaceDictionaryEntries`	→	`client.BatchDictionaryEntries`
`client.RestoreApiKey`	→	`client.RestoreApiKey`
`DictionaryClient.SaveDictionaryEntries`	→	`client.BatchDictionaryEntries`
`client.UpdateApiKey`	→	`client.UpdateApiKey`
`index.Batch`	→	`client.Batch`
`index.Browse`	→	`client.BrowseObjects`
`index.BrowseRules`	→	`client.BrowseRules`
`index.BrowseSynonyms`	→	`client.BrowseSynonyms`
`index.ClearObjects`	→	`client.ClearObjects`
`index.ClearRules`	→	`client.ClearRules`
`index.ClearSynonyms`	→	`client.ClearSynonyms`
`index.CopySettings`	→	`client.OperationIndex`
`index.Delete`	→	`client.DeleteIndex`
`index.DeleteBy`	→	`client.DeleteBy`
`index.DeleteObject`	→	`client.DeleteObject`
`index.DeleteObjects`	→	`client.DeleteObjects`
`index.DeleteRule`	→	`client.DeleteRule`
`index.DeleteSynonym`	→	`client.DeleteSynonym`
`index.FindObject`	→	`client.SearchSingleIndex`
`index.GetObject`	→	`client.GetObject`
`index.GetObjects`	→	`client.GetObjects`
`index.GetRule`	→	`client.GetRule`
`index.GetSettings`	→	`client.GetSettings`
`index.GetSynonym`	→	`client.GetSynonym`
`index.GetTask`	→	`client.GetTask`
`index.PartialUpdateObject`	→	`client.PartialUpdateObject`
`index.PartialUpdateObjects`	→	`client.PartialUpdateObjects`
`index.ReplaceAllObjects`	→	`client.ReplaceAllObjects`
`index.ReplaceAllRules`	→	`client.SaveRules`
`index.ReplaceAllSynonyms`	→	`client.SaveSynonyms`
`index.SaveObject`	→	`client.SaveObject`
`index.SaveObjects`	→	`client.SaveObjects`
`index.SaveRule`	→	`client.SaveRule`
`index.SaveRules`	→	`client.SaveRules`
`index.SaveSynonym`	→	`client.SaveSynonym`
`index.SaveSynonyms`	→	`client.SaveSynonyms`
`index.Search`	→	`client.SearchSingleIndex`
`index.SearchForFacetValues`	→	`client.SearchForFacetValues`
`index.SearchRules`	→	`client.SearchRules`
`index.SearchSynonyms`	→	`client.SearchSynonyms`
`index.SetSettings`	→	`client.SetSettings`
`index.{operation}.Wait`	→	`client.WaitForTask`

Version 6 (legacy)		Version 7 (current)
`client.GetFrequentlyBoughtTogether`	→	`client.GetRecommendations`
`client.GetRecommendations`	→	`client.GetRecommendations`
`client.GetRelatedProducts`	→	`client.GetRecommendations`

API clients (current)

Clients and methods

Upgrade the C# API client to version 7

Update your dependencies

Update imports

Update client initialization

Synchronous and asynchronous methods

Remove `InitIndex`

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Update the serialization library

Update enumeration serialization

Method changes reference

Search API client

API clients (current)

Clients and methods

​Update your dependencies

​Update imports

​Update client initialization

​Synchronous and asynchronous methods

​Remove InitIndex

​Update search calls

​Search a single index

​Search multiple indices

​Search for facet values

​Update indexing operations

​Add or replace records

​Partially update records

​Delete records

​Update settings, synonyms, and rules

​Get and set settings

​Save synonyms and rules

​Update index management

​Copy an index

​Move (rename) an index

​Copy only rules or settings

​Update task handling

​Update the serialization library

​Update enumeration serialization

​Method changes reference

​Search API client

​Recommend API client

Update your dependencies

Update imports

Update client initialization

Synchronous and asynchronous methods

Remove `InitIndex`

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Update the serialization library

Update enumeration serialization

Method changes reference

Search API client

Recommend API client