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

# Add a new record (with auto-generated object ID)

> Adds a record to an index or replaces it.

* If the record doesn't have an object ID, a new record with an auto-generated object ID is added to your index.
* If a record with the specified object ID exists, the existing record is replaced.
* If a record with the specified object ID doesn't exist, a new record is added to your index.
* If you add a record to an index that doesn't exist yet, a new index is created.

To update *some* attributes of a record, use the [`partial` operation](https://www.algolia.com/doc/rest-api/search/partial-update-object).
To add, update, or replace multiple records, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).

This operation is subject to [indexing rate limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).

**Required ACL:** `addObject`


## OpenAPI

````yaml specs/search.yml post /1/indexes/{indexName}
openapi: 3.1.0
info:
  title: Search API
  summary: >-
    The Algolia Search API lets you search, configure, and manage your indices
    and records
  description: >
    ## Client libraries


    Use Algolia's API clients and libraries to reliably integrate Algolia's APIs
    with your apps.

    The official API clients are covered by Algolia's [Service Level
    Agreement](https://www.algolia.com/policies/sla).


    For more information, see [Algolia's
    ecosystem](https://www.algolia.com/doc/libraries).


    ## Base URLs


    Base URLs for the Search API:


    - `https://{APPLICATION_ID}.algolia.net`

    - `https://{APPLICATION_ID}-dsn.algolia.net`.
      If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
      this ensures that requests are sent to servers closest to users.

    Both URLs provide high availability by distributing requests with load
    balancing.


    **All requests must use HTTPS.**


    ## Retry strategy


    To guarantee high availability, implement a retry strategy for all API
    requests using the URLs of your servers as fallbacks:


    - `https://{APPLICATION_ID}-1.algolianet.com`

    - `https://{APPLICATION_ID}-2.algolianet.com`

    - `https://{APPLICATION_ID}-3.algolianet.com`


    These URLs use a different DNS provider than the primary URLs.

    Randomize this list to ensure an even load across the three servers.


    All Algolia API clients implement this retry strategy.


    ## Authentication


    Add these headers to authenticate requests:


    - `x-algolia-application-id`. Your Algolia application ID.

    - `x-algolia-api-key`. An API key with the necessary permissions to make the
    request.
      The required access control list (ACL) to make a request is listed in each endpoint's reference.

    You can find your application ID and API key in the [Algolia
    dashboard](https://dashboard.algolia.com/account/api-keys).


    ## Request format


    Depending on the endpoint, request bodies are either JSON objects or arrays
    of JSON objects.


    ## Parameters


    Parameters are passed as query parameters for GET and DELETE requests,

    and in the request body for POST and PUT requests.


    Query parameters must be
    [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).

    Non-ASCII characters must be UTF-8 encoded.

    Plus characters (`+`) are interpreted as spaces.

    Arrays as query parameters must be one of:


    - A comma-separated string: `attributesToRetrieve=title,description`

    - A URL-encoded JSON array:
    `attributesToRetrieve=%5B%22title%22,%22description%22%D`


    ## Response status and errors


    The Search API returns JSON responses.

    Since JSON doesn't guarantee any specific ordering, don't rely on the order
    of attributes in the API response.


    Successful responses return `2xx` statuses. Client errors return `4xx`
    statuses. Server errors return `5xx` statuses.

    Error responses have a `message` property with more information.


    ## Version


    The current version of the Search API is version 1, indicated by the `/1/`
    in each endpoint's URL.
  version: 1.0.0
servers:
  - url: https://{appId}.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-1.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-2.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-3.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-dsn.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
security:
  - appId: []
    apiKey: []
tags:
  - name: Advanced
    description: Query your logs.
  - name: Api Keys
    x-displayName: API keys
    description: >
      Manage your API keys.


      API requests must be authenticated with an API key.

      API keys can have permissions (access control lists, ACL) and
      restrictions.
    externalDocs:
      url: https://www.algolia.com/doc/guides/security/api-keys
      description: API keys.
  - name: Clusters
    description: |
      Multi-cluster operations.

      Multi-cluster operations are **deprecated**.
      If you have issues with your Algolia infrastructure
      due to large volumes of data, contact the Algolia support team.
  - name: Dictionaries
    description: >
      Manage your dictionaries.


      Customize language-specific settings, such as stop words, plurals, or word
      segmentation.


      Dictionaries are application-wide.
    externalDocs:
      url: >-
        https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp
      description: Natural languages.
  - name: Indices
    description: >
      Manage your indices and index settings.


      Indices are copies of your data that are stored on Algolia's servers.

      They're optimal data structures for fast search and are made up of records
      and settings.
    externalDocs:
      url: >-
        https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices
      description: Manage your indices.
  - name: Records
    description: >
      Add, update, and delete records from your indices.


      Records are individual items in your index.

      When they match a search query, they're returned as search results, in the
      order determined by your ranking.

      Records are schemaless JSON objects.

      When adding or updating many records, check the [indexing rate
      limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
    externalDocs:
      url: >-
        https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data
      description: Prepare your records.
  - name: Rules
    description: >
      Create, update, delete, and search for rules.


      Rules are _if-then_ statements that you can use to curate search results.

      Rules have _conditions_ that can trigger _consequences_.

      Consequences are changes to the search results, such as changing the order
      of search results or boosting a facet.

      This can be useful for tuning specific queries or for merchandising.
    externalDocs:
      url: https://www.algolia.com/doc/guides/managing-results/rules/rules-overview
      description: Index Rules.
  - name: Search
    description: Search one or more indices for matching records or facet values.
  - name: Synonyms
    description: |
      Create, update, delete, and search for synonyms.

      Synonyms are terms that the search engine should consider equal.
    externalDocs:
      url: >-
        https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms
      description: Synonyms.
  - name: Vaults
    description: >-
      Algolia Vault lets you restrict access to your clusters to specific IP
      addresses and provides disk-level encryption at rest.
    externalDocs:
      url: https://www.algolia.com/doc/guides/security/algolia-vault
      description: Algolia Vault.
  - name: _model_index_settings
    x-displayName: Index settings
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/indexSettings" />.
paths:
  /1/indexes/{indexName}:
    post:
      tags:
        - Records
      summary: Add a new record (with auto-generated object ID)
      description: >
        Adds a record to an index or replaces it.


        - If the record doesn't have an object ID, a new record with an
        auto-generated object ID is added to your index.

        - If a record with the specified object ID exists, the existing record
        is replaced.

        - If a record with the specified object ID doesn't exist, a new record
        is added to your index.

        - If you add a record to an index that doesn't exist yet, a new index is
        created.


        To update _some_ attributes of a record, use the [`partial`
        operation](https://www.algolia.com/doc/rest-api/search/partial-update-object).

        To add, update, or replace multiple records, use the [`batch`
        operation](https://www.algolia.com/doc/rest-api/search/batch).


        This operation is subject to [indexing rate
        limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
      operationId: saveObject
      parameters:
        - $ref: '#/components/parameters/IndexName'
      requestBody:
        required: true
        description: >-
          The record. A schemaless object with attributes that are useful in the
          context of search and discovery.
        x-is-generic: true
        content:
          application/json:
            schema:
              type: object
              example:
                objectID: blackTShirt
                name: Black T-shirt
                color: '#000000'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                title: saveObjectResponse
                type: object
                additionalProperties: false
                properties:
                  createdAt:
                    $ref: '#/components/schemas/createdAt'
                  taskID:
                    $ref: '#/components/schemas/taskID'
                  objectID:
                    $ref: '#/components/schemas/objectID'
                required:
                  - taskID
                  - createdAt
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      x-codeSamples:
        - lang: csharp
          label: C#
          source: >-
            // Initialize the client

            var client = new SearchClient(new
            SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY"));


            // Call the API

            var response = await client.SaveObjectAsync(
              "<YOUR_INDEX_NAME>",
              new Dictionary<string, string>
              {
                { "name", "Black T-shirt" },
                { "color", "#000000||black" },
                { "availableIn", "https://source.unsplash.com/100x100/?paris||Paris" },
                { "objectID", "myID" },
              }
            );


            // print the response

            Console.WriteLine(response);
        - lang: dart
          label: Dart
          source: |-
            // Initialize the client
            final client =
                SearchClient(appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY');

            // Call the API
            final response = await client.saveObject(
              indexName: "<YOUR_INDEX_NAME>",
              body: {
                'name': "Black T-shirt",
                'color': "#000000||black",
                'availableIn': "https://source.unsplash.com/100x100/?paris||Paris",
                'objectID': "myID",
              },
            );

            // print the response
            print(response);
        - lang: go
          label: Go
          source: >-
            // Initialize the client

            client, err := search.NewClient("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY")

            if err != nil {
              // The client can fail to initialize if you pass an invalid parameter.
              panic(err)
            }


            // Call the API

            response, err := client.SaveObject(client.NewApiSaveObjectRequest(
              "<YOUR_INDEX_NAME>",
              map[string]any{
                "name":        "Black T-shirt",
                "color":       "#000000||black",
                "availableIn": "https://source.unsplash.com/100x100/?paris||Paris",
                "objectID":    "myID",
              },
            ))

            if err != nil {
              // handle the eventual error
              panic(err)
            }



            // print the response

            print(response)
        - lang: java
          label: Java
          source: >-
            // Initialize the client

            SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY");


            // Call the API

            SaveObjectResponse response = client.saveObject(
              "<YOUR_INDEX_NAME>",
              new HashMap() {
                {
                  put("name", "Black T-shirt");
                  put("color", "#000000||black");
                  put("availableIn", "https://source.unsplash.com/100x100/?paris||Paris");
                  put("objectID", "myID");
                }
              }
            );


            // print the response

            System.out.println(response);
        - lang: javascript
          label: JavaScript
          source: >-
            // Initialize the client

            const client = algoliasearch('ALGOLIA_APPLICATION_ID',
            'ALGOLIA_API_KEY');


            // Call the API

            const response = await client.saveObject({
              indexName: '<YOUR_INDEX_NAME>',
              body: {
                name: 'Black T-shirt',
                color: '#000000||black',
                availableIn: 'https://source.unsplash.com/100x100/?paris||Paris',
                objectID: 'myID',
              },
            });



            // print the response

            console.log(response);
        - lang: kotlin
          label: Kotlin
          source: >-
            // Initialize the client

            val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey =
            "ALGOLIA_API_KEY")


            // Call the API

            var response =
              client.saveObject(
                indexName = "<YOUR_INDEX_NAME>",
                body =
                  buildJsonObject {
                    put("name", JsonPrimitive("Black T-shirt"))
                    put("color", JsonPrimitive("#000000||black"))
                    put("availableIn", JsonPrimitive("https://source.unsplash.com/100x100/?paris||Paris"))
                    put("objectID", JsonPrimitive("myID"))
                  },
              )


            // print the response

            println(response)
        - lang: php
          label: PHP
          source: >-
            // Initialize the client

            $client = SearchClient::create('ALGOLIA_APPLICATION_ID',
            'ALGOLIA_API_KEY');


            // Call the API

            $response = $client->saveObject(
                '<YOUR_INDEX_NAME>',
                ['name' => 'Black T-shirt',
                    'color' => '#000000||black',
                    'availableIn' => 'https://source.unsplash.com/100x100/?paris||Paris',
                    'objectID' => 'myID',
                ],
            );



            // print the response

            var_dump($response);
        - lang: python
          label: Python
          source: >-
            # Initialize the client

            # In an asynchronous context, you can use SearchClient instead,
            which exposes the exact same methods.

            client = SearchClientSync("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY")


            # Call the API

            response = client.save_object(
                index_name="<YOUR_INDEX_NAME>",
                body={
                    "name": "Black T-shirt",
                    "color": "#000000||black",
                    "availableIn": "https://source.unsplash.com/100x100/?paris||Paris",
                    "objectID": "myID",
                },
            )



            # print the response

            print(response)
        - lang: ruby
          label: Ruby
          source: >-
            # Initialize the client

            client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY")


            # Call the API

            response = client.save_object(
              "<YOUR_INDEX_NAME>",
              {
                name: "Black T-shirt",
                color: "#000000||black",
                availableIn: "https://source.unsplash.com/100x100/?paris||Paris",
                objectID: "myID"
              }
            )



            # print the response

            puts(response)
        - lang: scala
          label: Scala
          source: >-
            // Initialize the client

            val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey =
            "ALGOLIA_API_KEY")


            // Call the API

            val response = Await.result(
              client.saveObject(
                indexName = "<YOUR_INDEX_NAME>",
                body = JObject(
                  List(
                    JField("name", JString("Black T-shirt")),
                    JField("color", JString("#000000||black")),
                    JField("availableIn", JString("https://source.unsplash.com/100x100/?paris||Paris")),
                    JField("objectID", JString("myID"))
                  )
                )
              ),
              Duration(100, "sec")
            )


            // print the response

            println(response)
        - lang: swift
          label: Swift
          source: >-
            // Initialize the client

            let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID",
            apiKey: "ALGOLIA_API_KEY")


            // Call the API

            let response = try await client.saveObject(
                indexName: "<YOUR_INDEX_NAME>",
                body: [
                    "name": "Black T-shirt",
                    "color": "#000000||black",
                    "availableIn": "https://source.unsplash.com/100x100/?paris||Paris",
                    "objectID": "myID",
                ]
            )


            // print the response

            print(response)
        - lang: cURL
          label: curl
          source: |-
            curl --request POST \
              --url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME \
              --header 'accept: application/json' \
              --header 'content-type: application/json' \
              --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
              --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
              --data '
            {
              "objectID": "blackTShirt",
              "name": "Black T-shirt",
              "color": "#000000"
            }
            '
components:
  parameters:
    IndexName:
      name: indexName
      in: path
      description: Name of the index on which to perform the operation.
      required: true
      schema:
        type: string
        example: ALGOLIA_INDEX_NAME
  schemas:
    createdAt:
      type: string
      example: '2023-07-04T12:49:15Z'
      description: Date and time when the object was created, in RFC 3339 format.
    taskID:
      type: integer
      format: int64
      example: 1514562690001
      description: >
        Unique identifier of a task.


        A successful API response means that a task was added to a queue.

        It might not run immediately.

        You can check the task's progress with the [`task`
        operation](https://www.algolia.com/doc/rest-api/search/get-task) and
        this task ID.
    objectID:
      type: string
      description: Unique record identifier.
      example: test-record-123
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-algolia-application-id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: x-algolia-api-key
      description: >
        Your Algolia API key with the necessary permissions to make the request.

        Permissions are controlled through access control lists (ACL) and access
        restrictions.

        The required ACL to make a request is listed in each endpoint's
        reference.

````