Custom Web API vectorizer

The Custom Web API vectorizer lets you configure search queries to call a web API endpoint that generates embeddings at query time. The required JSON payload structure for the endpoint is described later in this article. Your data is processed in the geography where your model is deployed.

Although vectorizers are used at query time, you specify them in index definitions and reference them on vector fields through a vector profile. For more information, see Configure a vectorizer in a search index.

The custom web API vectorizer is called WebApiVectorizer in the REST API. Use the latest stable version of Indexes - Create (REST API) or an Azure SDK package that provides the feature.

Vectorizer parameters

Parameters are case sensitive.

Supported vector query types

The Custom Web API vectorizer supports text, imageUrl, and imageBinary vector queries.

Sample definition

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

Update header values after GET

When you retrieve an index definition with GET or list indexes with LIST, the service returns <redacted> for every httpHeaders value in a Custom Web API vectorizer. For example:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

To reuse the stored api-key value, update the same existing vectorizer with the same name, kind, and endpoint. Resubmit the returned placeholder for the matching header name:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

For the same existing vectorizer and endpoint, you can mix <redacted> or <unchanged> for retained header values with actual replacement values. Explicit values take precedence over placeholders. Provide an actual value for each added or renamed header because a placeholder requires an unambiguous existing source. For URI-query changes, see URI redaction and credential-preserving updates.

If you change the endpoint, provide actual URI and header secrets in the same update. The service doesn't reuse stored secrets for a different endpoint:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://new.contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<new-header-value>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

If the credentials are unavailable and you must change the endpoint, rotate or regenerate them at the external endpoint. Then submit the new uri and header values together.

The <redacted> value is a service sentinel, not a credential. It can't create a vectorizer or retrieve or reuse a header value stored for another vectorizer.

URI redaction and credential-preserving updates

This URI-query behavior applies to all API versions.

When you retrieve an index with GET or list indexes with LIST, Azure AI Search redacts sensitive Custom Web API URI query values, including sig and code, and HTTP header values. These redacted values protect shared access signature (SAS) signatures, function keys, and header credentials.

To retain stored secrets, update the same existing resource and endpoint. Submit the returned <redacted> or <unchanged> placeholders in the management PUT request. This PUT updates the index definition; it isn't the endpoint invocation controlled by the vectorizer's httpMethod. You can also set the whole uri to <unchanged> to retain the stored URI.

Secret values aren't carried to a different endpoint or copied into a new resource. Changing an endpoint, cloning a redacted definition, or otherwise repointing a resource requires explicit secrets.

If the service can't identify one unambiguous existing source for a placeholder, the PUT fails with 400 Bad Request and requests the actual secret value. An unresolved or persisted placeholder isn't a usable credential. Secret restoration is atomic: a failed restoration doesn't partially apply URI or header changes.

You can provide replacement URI or header secrets at any time. Explicit values take precedence over placeholders.

URI-query updates follow these rules:

• For an Azure Function code parameter, you can update other non-secret query parameters while retaining the stored function key for the same endpoint.
• For a SAS sig parameter, the signature is bound to the surrounding non-secret query configuration. If scope, permissions, expiry, resource, version, ordering, casing, or encoding changes, provide a new signature. Even semantically equivalent reordered or re-encoded query text requires a new signature.

Secret query parameter names are recognized case-insensitively and when percent-encoded. The service preserves your URI representation rather than normalizing it. Repeated secret parameters are matched by occurrence. If their occurrence pattern no longer aligns with the stored URI, provide actual values.

Existing GET-then-PUT workflows using <redacted> or <unchanged> remain supported. For header examples, see Update header values after GET.

For custom skills, see Custom Web API skill URI redaction and credential-preserving updates.

JSON payload structure

The required JSON payload structure for an endpoint used with the Custom Web API vectorizer is the same as the structure used by the Custom Web API skill. For more information, see the skill documentation.

Keep the following considerations in mind when implementing a web API endpoint for the Custom Web API vectorizer:

• The vectorizer sends only one record at a time in the values array when making a request to the endpoint.

• The vectorizer passes the data to be vectorized in a specific key in the data JSON object in the request payload. That key is text, imageUrl, or imageBinary, depending on which type of vector query was requested.

• The vectorizer expects the resulting embedding to be under the vector key in the data JSON object in the response payload.

• The vectorizer ignores any errors or warnings returned by the endpoint. These errors and warnings aren't available for query-time debugging.

• If an imageBinary vector query was requested, the request payload sent to the endpoint is the following:

  {
      "values": [
          {
              "recordId": "0",
              "data":
              {
                  "imageBinary": {
                      "data": "<base 64 encoded image binary data>"
                  }
              }
          }
      ]
  }
  

See also

• Integrated vectorization
• How to configure a vectorizer in a search index
• Custom Web API skill