---
title: "Create an encoder"
method: POST
path: "/v2/encoders"
tags: ["Encoders"]
---

# Create an encoder

`POST /v2/encoders`

Creates a new encoder.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- union — Request to create a new encoder. Use `openai-compatible` for text-only endpoints that implement OpenAI's `/v1/embeddings`. Use `vllm-compatible` for endpoints that additionally support image embeddings.
  - object — Configuration for a text-only encoder served by an endpoint that implements OpenAI's `/v1/embeddings` request shape.
    - `type` string, required — Must be "openai-compatible" for OpenAI and OpenAI-compatible text-embedding APIs.
    - `name` string, required — A unique name for the encoder.
    - `description` string, required — A description of what this encoder does.
    - `output_dimensions` integer — The number of dimensions in the output embedding vector. If provided and the model supports truncation, the response is truncated to this number of dimensions.
    - `uri` string, uri, required — The URI endpoint for the embedding API (can be OpenAI or any compatible embedding API endpoint)
    - `model` string, required — The model name to use for embeddings
    - `auth` union — Authentication configuration for connecting to a remote service.
      - object — Bearer token authentication
        - `type` string, required — Must be "bearer" for bearer token auth
        - `token` string, required — The bearer token to use for authentication
      - object — Custom header-based authentication
        - `type` string, required — Must be "header" for header-based auth
        - `header` string, required — The header name to use (e.g. x-api-key)
        - `value` string, required — The header value to use
      - object — OAuth 2.0 client credentials authentication. The platform acquires an access token from the token endpoint before connecting to the remote service.
        - `type` string, required — Must be "oauth_client_credentials" for OAuth client credentials auth.
        - `client_id` string, required — The OAuth2 client ID.
        - `client_secret` string, required — The OAuth2 client secret.
        - `token_endpoint` string, uri, required — The OAuth2 token endpoint URL where the platform exchanges credentials for an access token.
        - `scopes` string[] — OAuth2 scopes to request when acquiring the access token.
        - `audience` string — Sent as the OAuth `audience` form parameter so the identity provider mints a token whose `aud` claim targets this value. Required by some identity providers, such as Ory Hydra and Auth0.
        - `client_auth_method` 'client_secret_basic' | 'client_secret_post' — How the platform presents the client ID and secret to the token endpoint, named after the OAuth `token_endpoint_auth_method` registry. `client_secret_basic` sends them in an HTTP Basic `Authorization` header. `client_secret_post` sends them as `client_id` and `client_secret` form fields in the request body. Set this to the method the client application is registered with at the identity provider.
  - object — Configuration for a vLLM-served embedding encoder. The endpoint must accept text-embedding requests and, when `image_encoding` is true, image-embedding requests.
    - `type` string, required — Must be "vllm-compatible" for vLLM-served embedding endpoints.
    - `name` string, required — A unique name for the encoder.
    - `description` string, required — A description of what this encoder does.
    - `output_dimensions` integer — The number of dimensions in the output embedding vector. If provided and the model supports truncation, the response is truncated to this number of dimensions.
    - `uri` string, uri, required — The URI endpoint for the vLLM embedding API.
    - `model` string, required — The model name to use for embeddings.
    - `auth` union — Authentication configuration for connecting to a remote service.
      - object — Bearer token authentication
        - `type` string, required — Must be "bearer" for bearer token auth
        - `token` string, required — The bearer token to use for authentication
      - object — Custom header-based authentication
        - `type` string, required — Must be "header" for header-based auth
        - `header` string, required — The header name to use (e.g. x-api-key)
        - `value` string, required — The header value to use
      - object — OAuth 2.0 client credentials authentication. The platform acquires an access token from the token endpoint before connecting to the remote service.
        - `type` string, required — Must be "oauth_client_credentials" for OAuth client credentials auth.
        - `client_id` string, required — The OAuth2 client ID.
        - `client_secret` string, required — The OAuth2 client secret.
        - `token_endpoint` string, uri, required — The OAuth2 token endpoint URL where the platform exchanges credentials for an access token.
        - `scopes` string[] — OAuth2 scopes to request when acquiring the access token.
        - `audience` string — Sent as the OAuth `audience` form parameter so the identity provider mints a token whose `aud` claim targets this value. Required by some identity providers, such as Ory Hydra and Auth0.
        - `client_auth_method` 'client_secret_basic' | 'client_secret_post' — How the platform presents the client ID and secret to the token endpoint, named after the OAuth `token_endpoint_auth_method` registry. `client_secret_basic` sends them in an HTTP Basic `Authorization` header. `client_secret_post` sends them as `client_id` and `client_secret` form fields in the request body. Set this to the method the client application is registered with at the identity provider.
    - `image_encoding` boolean — Whether the encoder produces image embeddings, either of an image alone or jointly with accompanying text. When `true`, the endpoint must accept image-embedding requests; the create call validates this and fails if the endpoint does not support them.

## Response `201`

The created encoder.

- Encoder — A model that converts text into vector embeddings for semantic search.
  - `id` string, required — The Encoder ID.
  - `name` string, required — The encoder name, for example `boomerang-2023-q3`.
  - `type` string — The encoder type
  - `output_dimensions` integer — The number of dimensions in the output embedding. A high dimensionality consumes more storage space but can increase the quality of the embedding.
  - `description` string — The encoder description.
  - `default` boolean — Indicates whether this is the default encoder used when you create a corpus.
  - `enabled` boolean — Indicates whether the encoder is enabled.
  - `image_encoding` boolean — Whether this encoder can produce embeddings for images, either of an image alone or jointly with accompanying text.

## Other responses

- `400` — Encoder creation request was malformed.
- `403` — Permissions do not allow creating an encoder

## Changes

- **2026-09-23** `3f4075adad3d` — 4 info
  - added the new optional request property `oneOf[#/components/schemas/CreateOpenAIEncoderRequest]/auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/audience`
  - added the new optional request property `oneOf[#/components/schemas/CreateOpenAIEncoderRequest]/auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/client_auth_method`
  - added the new optional request property `oneOf[#/components/schemas/CreateVLlmEncoderRequest]/auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/audience`
  - added the new optional request property `oneOf[#/components/schemas/CreateVLlmEncoderRequest]/auth/oneOf[#/components/schemas/OAuthClientCredentialsAuth]/client_auth_method`

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/encoders/post.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/5cd882cb3cda?raw)