> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt > Use this file to discover all available pages before exploring further. # Convert an index into a document index > Convert a serverless vector index or legacy integrated index into a new document index. The source index isn't changed, and the new index holds a snapshot of the source taken when the job starts. The request returns once the new index is created in the `Initializing` state. Track the job with [Describe a conversion job](https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_conversion_job). If the job fails or is canceled, the index is left in the `InitializationFailed` state with no usable data. Delete it to free its name. A job that fails because of your data is charged for the data it read, and a canceled job isn't charged. For how source records map to the schema, see [Convert an index](https://docs.pinecone.io/guides/index-data/convert-an-index). ```bash Vector index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/support-tickets/convert \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'Content-Type: application/json' \ -d '{ "name": "support-tickets-docs", "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" }, "ticket_text": { "type": "string", "full_text_search": { "language": "en" } } } }, "error_mode": { "on_error": "continue" } }' ``` ```bash Legacy integrated index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/support-articles/convert \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'Content-Type: application/json' \ -d '{ "name": "support-articles-docs", "schema": { "fields": { "chunk_text": { "type": "string", "embed": { "model": "multilingual-e5-large" } } } } }' ``` ## OpenAPI ````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes/{index_name}/convert openapi: 3.0.3 info: title: Pinecone Control Plane API description: >- Pinecone is a vector database that makes it easy to search and retrieve billions of high-dimensional vectors. contact: name: Pinecone Support url: https://support.pinecone.io email: support@pinecone.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 2026-07 servers: - url: https://api.pinecone.io description: Production API endpoints security: - ApiKeyAuth: [] tags: - name: Manage Indexes description: Actions that manage indexes externalDocs: description: More Pinecone.io API docs url: https://docs.pinecone.io/introduction paths: /indexes/{index_name}/convert: post: tags: - Manage Indexes summary: Convert an index into a document index description: >- Convert a serverless vector index or legacy integrated index into a new document index. The source index isn't changed, and the new index holds a snapshot of the source taken when the job starts. The request returns once the new index is created in the `Initializing` state. Track the job with [Describe a conversion job](https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_conversion_job). If the job fails or is canceled, the index is left in the `InitializationFailed` state with no usable data. Delete it to free its name. A job that fails because of your data is charged for the data it read, and a canceled job isn't charged. For how source records map to the schema, see [Convert an index](https://docs.pinecone.io/guides/index-data/convert-an-index). operationId: convert_index parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 2026-07 type: string style: simple - in: path name: index_name description: The name of the vector index to convert. required: true schema: type: string example: example-index style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/ConvertIndexRequest' examples: dense-with-text: summary: >- Keep the dense vectors and add full-text search over a metadata field description: >- The source holds 1536-dimension cosine vectors and a `chunk_text` metadata string on each record. The new index keeps the vectors in `embedding` and indexes `chunk_text` for full-text search. value: name: example-index-docs schema: fields: chunk_text: full_text_search: language: en type: string embedding: dimension: 1536 metric: cosine type: dense_vector skip-bad-records: summary: Skip records the new index cannot take value: error_mode: on_error: continue name: example-index-docs schema: fields: chunk_text: full_text_search: {} type: string embedding: dimension: 1536 metric: cosine type: dense_vector required: true responses: '202': description: The new index has been created and the conversion job queued. content: application/json: schema: $ref: '#/components/schemas/ConvertIndexResponse' '400': description: >- The request is invalid, or the index cannot be converted into the requested schema. The message names the problem and how to fix it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: pod-source: summary: The source is a pod-based index value: error: code: INVALID_ARGUMENT message: >- Index example-index is a pod-based index. Only serverless indexes can be converted; migrate it to serverless first. status: 400 byoc-source: summary: The source is a BYOC index value: error: code: INVALID_ARGUMENT message: >- Index example-index is in a BYOC environment. BYOC indexes cannot be converted. status: 400 schema-exists: summary: The source already has a document schema value: error: code: INVALID_ARGUMENT message: >- Index example-index already has a document schema. Only vector indexes can be converted. status: 400 dimension-mismatch: summary: The schema cannot hold the source vectors value: error: code: INVALID_ARGUMENT message: >- The schema needs a dense_vector field with dimension 1536 to hold the vectors of index example-index. Set the dense field's dimension to 1536. status: 400 metric-mismatch: summary: The dense field uses a different metric than the source value: error: code: INVALID_ARGUMENT message: >- Field embedding uses metric euclidean, but index example-index uses cosine. Set the field's metric to cosine so scores keep their meaning. status: 400 invalid-error-mode: summary: Unknown on_error value value: error: code: INVALID_ARGUMENT message: >- Invalid on_error behavior specified. Use "continue" or "abort". status: 400 '401': description: 'Unauthorized. Possible causes: missing or invalid API key.' content: text/plain: schema: $ref: '#/components/schemas/UnauthorizedMessage' '402': description: >- Payment required. Organization is on a paid plan and is delinquent on payment. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: payment-required: summary: Payment required value: error: code: PAYMENT_REQUIRED message: >- Request failed. Pay all past due invoices to lift restrictions on your account. status: 402 '403': description: >- Forbidden. Possible causes: the API key lacks the permission to create indexes, the project's index quota is exhausted, or the organization is on the Starter or Builder plan, where index conversion isn't available. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: permission-denied: summary: Missing permission value: error: code: PERMISSION_DENIED message: >- Access denied: Permission control::index::create is required status: 403 quota-exceeded: summary: Index quota exhausted value: error: code: FORBIDDEN message: Increase your quota or upgrade to create more indexes. status: 403 plan-not-supported: summary: Plan doesn't include conversion value: error: code: PERMISSION_DENIED message: >- Index conversion isn't available on the Starter plan. Upgrade to Standard or Enterprise to convert indexes: https://app.pinecone.io/organizations/-/settings/billing/plans status: 403 '404': description: Index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: index-not-found: summary: Index not found value: error: code: NOT_FOUND message: Index example-index not found. status: 404 '409': description: >- An index with the requested `name` already exists in the project, including an index created by an earlier request to convert. Choose another name, or find the earlier job with List conversion jobs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: index-name-already-exists: summary: Index name needs to be unique value: error: code: ALREADY_EXISTS message: >- Index example-index-docs already exists. Choose another name. To check an earlier conversion into it, list conversion jobs. status: 409 '412': description: >- The source index cannot be converted in its current state: it is not `Ready`. Wait until the index is `Ready`, then retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: source-not-ready: summary: The source index is still initializing. value: error: code: FAILED_PRECONDITION message: >- Index example-index is Initializing. Wait until it is Ready, then retry. status: 412 '422': description: >- Unprocessable entity. The request body is valid JSON but could not be deserialized into the request type, for example because it has an unknown key, a missing required key, or a value of the wrong type. The body is a plain-text message naming the problem and where it occurred, not an `ErrorResponse`. content: text/plain: schema: $ref: '#/components/schemas/UnprocessableEntityMessage' examples: missing-field: summary: A required key is missing value: >- Failed to deserialize the JSON body into the target type: missing field `metric` at line 1 column 16 unknown-field: summary: An unknown key value: >- Failed to deserialize the JSON body into the target type: schema.fields.score: unknown field `embed`, expected `description` or `filterable` at line 1 column 98 '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-server-error: summary: Internal server error value: error: code: UNKNOWN message: Internal server error status: 500 components: schemas: ConvertIndexRequest: description: >- The configuration of the document index a vector index is converted into. type: object properties: name: example: example-index description: >- The name of the index. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'. type: string minLength: 1 maxLength: 45 schema: $ref: '#/components/schemas/CreateIndexSchema' error_mode: $ref: '#/components/schemas/ConversionErrorMode' tags: $ref: '#/components/schemas/IndexTags' deletion_protection: $ref: '#/components/schemas/DeletionProtection' read_capacity: $ref: '#/components/schemas/ReadCapacity' required: - name - schema additionalProperties: false ConvertIndexResponse: description: The response for converting an index. type: object properties: conversion_job_id: example: 670e8400-e29b-41d4-a716-446655440001 description: >- Pass to Describe a conversion job to track the conversion's progress. type: string index_id: example: 123e4567-e89b-12d3-a456-426614174000 description: The ID of the document index that was created. type: string required: - conversion_job_id - index_id ErrorResponse: example: error: code: INVALID_ARGUMENT message: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. status: 400 description: The response shape used for all error responses. type: object properties: status: example: 500 description: The HTTP status code of the error. type: integer error: example: code: INVALID_ARGUMENT message: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. description: Detailed information about the error that occurred. type: object properties: code: description: >- The error code. Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`, `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, `PAYLOAD_TOO_LARGE`, or `UNPROCESSABLE_ENTITY`. x-enum: - OK - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - INTERNAL - FORBIDDEN - PAYMENT_REQUIRED - SERVICE_UNAVAILABLE - PAYLOAD_TOO_LARGE - UNPROCESSABLE_ENTITY type: string message: example: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. description: A human-readable description of the error type: string details: description: >- Additional information about the error. This field is not guaranteed to be present. type: object required: - code - message required: - status - error UnauthorizedMessage: example: Invalid API key description: >- The plain-text body of a `401` response. Authentication failures are rejected before the request reaches the API, so they carry a short message rather than an `ErrorResponse`. type: string UnprocessableEntityMessage: example: >- Failed to deserialize the JSON body into the target type: missing field `metric` at line 1 column 16 description: >- The plain-text body of a `422` response. A request body that cannot be deserialized is rejected before the request reaches the API, so it carries the deserializer's message rather than an `ErrorResponse`. type: string CreateIndexSchema: example: fields: body: full_text_search: language: en type: string your_vector: dimension: 1536 metric: cosine type: dense_vector description: >- The fields the index searches over: dense vectors, sparse vectors, and string fields searched by full-text search or by embeddings Pinecone derives from their text. An index has one dense vector slot and one sparse vector slot: at most one field can be a `dense_vector` field or declare `embed`, and at most one can be a `sparse_vector` field or declare `sparse_embed`. Metadata isn't declared in the schema; it's indexed automatically from the documents you upsert. type: object properties: fields: description: >- A map of field names to field configurations. Names are at most 64 bytes and can't start with `$`. Names starting with `_` are reserved; to create a vector index with the reserved `_values` and `_sparse_values` fields, see [Adopt the Documents API](https://docs.pinecone.io/guides/index-data/adopt-the-documents-api#what-this-means-for-your-existing-code). type: object additionalProperties: $ref: '#/components/schemas/CreateIndexSchemaField' minProperties: 1 required: - fields additionalProperties: false ConversionErrorMode: description: >- How a conversion handles a source record the new index cannot take, such as a record whose metadata value for a `full_text_search` field is not a string. Records the schema can hold are never affected. If omitted, `on_error` is `abort`. type: object properties: on_error: example: abort description: >- What a record the new index cannot take does to the conversion. Possible values: - `abort`: the conversion fails, and the job's `error` names the record and the reason. - `continue`: the record is skipped and counted in the job's `records_skipped`. x-enum: - abort - continue type: string IndexTags: nullable: true example: tag0: val0 tag1: val1 description: >- Custom user tags added to an index, at most 20 per index. Keys must be 80 characters or less and alphanumeric, '_', or '-'. Values must be 120 characters or less and consist of printable ASCII characters or spaces. To unset a key, set the value to be an empty string. `null` in responses when the index has no tags. type: object additionalProperties: type: string DeletionProtection: description: >- Whether [deletion protection](http://docs.pinecone.io/guides/manage-data/manage-indexes#configure-deletion-protection) is enabled/disabled for the index. Possible values: `disabled` or `enabled`. default: disabled x-enum: - disabled - enabled type: string ReadCapacity: description: >- By default the index will be created with read capacity mode `OnDemand`, for managed and BYOC indexes alike. If you prefer to allocate dedicated read nodes for your workload, you must specify mode `Dedicated` and additional configurations for `node_type` and `scaling`. discriminator: propertyName: mode mapping: OnDemand: '#/components/schemas/ReadCapacityOnDemandSpec' Dedicated: '#/components/schemas/ReadCapacityDedicatedSpec' oneOf: - $ref: '#/components/schemas/ReadCapacityOnDemandSpec' - $ref: '#/components/schemas/ReadCapacityDedicatedSpec' CreateIndexSchemaField: description: >- The configuration of a single field. `type` determines how the field is stored and searched. discriminator: propertyName: type mapping: dense_vector: '#/components/schemas/DenseVectorField' sparse_vector: '#/components/schemas/SparseVectorField' string: '#/components/schemas/StringField' oneOf: - $ref: '#/components/schemas/DenseVectorField' - $ref: '#/components/schemas/SparseVectorField' - $ref: '#/components/schemas/StringField' ReadCapacityOnDemandSpec: example: mode: OnDemand title: On-demand type: object properties: mode: description: >- The mode of the index. Possible values: `OnDemand` or `Dedicated`. Defaults to `OnDemand`. If set to `Dedicated`, `dedicated.node_type`, `dedicated.scaling`, and `dedicated.manual` must be specified. type: string required: - mode ReadCapacityDedicatedSpec: example: dedicated: manual: replicas: 1 shards: 1 node_type: t1 scaling: Manual mode: Dedicated title: Dedicated type: object properties: mode: description: >- The mode of the index. Possible values: `OnDemand` or `Dedicated`. Defaults to `OnDemand`. If set to `Dedicated`, `dedicated.node_type`, `dedicated.scaling`, and `dedicated.manual` must be specified. type: string dedicated: $ref: '#/components/schemas/ReadCapacityDedicatedConfig' required: - mode - dedicated DenseVectorField: example: dimension: 1536 metric: cosine type: dense_vector title: Dense vector description: >- A dense vector field configuration. Stores fixed-dimension floating-point vectors for approximate nearest-neighbor (ANN) search. type: object properties: type: description: Identifies this as a dense vector field. Must be `dense_vector`. type: string enum: - dense_vector description: nullable: true description: >- Optional description for this field, at most 256 bytes. `null` in responses when none was set. type: string maxLength: 256 dimension: example: 1536 description: The number of dimensions in the dense vectors stored in this field. type: integer format: int32 minimum: 1 maximum: 20000 metric: example: cosine description: |- The distance metric used for similarity search. Possible values: `cosine`, `dotproduct`, or `euclidean`. x-enum: - cosine - dotproduct - euclidean type: string required: - type - dimension - metric additionalProperties: false SparseVectorField: example: type: sparse_vector title: Sparse vector description: >- A sparse vector field configuration. Stores sparse vectors for keyword or hybrid search. type: object properties: type: description: Identifies this as a sparse vector field. Must be `sparse_vector`. type: string enum: - sparse_vector description: nullable: true description: >- Optional description for this field, at most 256 bytes. `null` in responses when none was set. type: string maxLength: 256 required: - type additionalProperties: false StringField: example: full_text_search: language: en type: string title: String description: >- A string field. Declare at least one of: - `full_text_search`: Index the text for full-text search. - `embed`: Embed the text with a hosted dense embedding model. - `sparse_embed`: Embed the text with a hosted sparse embedding model. Combine them to search the same text in more than one way. Each value is at most 100 KB. type: object properties: type: description: Identifies this as a string field. Must be `string`. type: string enum: - string description: description: Optional description for this field, at most 256 bytes. type: string maxLength: 256 full_text_search: description: >- Full-text search configuration. When present, the field is indexed for full-text search. `stop_words` requires `stemming: true`. `ngram` cannot be combined with `stemming` or `stop_words`. type: object properties: language: example: en description: The language for text analysis. default: en type: string stemming: description: Whether to apply stemming during text analysis. default: false type: boolean stop_words: description: >- Whether to filter stop words during text analysis. Requires `stemming: true`. default: false type: boolean ngram: description: >- Character n-gram tokenization for substring matching. When present, the field is tokenized into character n-grams instead of words. Cannot be combined with `stemming` or `stop_words`. type: object properties: min_gram: example: 2 description: Minimum n-gram length. Must be no greater than `max_gram`. type: integer minimum: 1 maximum: 10 max_gram: example: 3 description: Maximum n-gram length. type: integer minimum: 1 maximum: 10 prefix_only: description: >- When `true`, only prefix n-grams anchored at the start of the token are generated (e.g. for autocomplete). default: false type: boolean required: - min_gram - max_gram additionalProperties: false additionalProperties: false store_text: example: true description: >- Whether to store the field's text. A stored field is always indexed for full-text search, with default settings if `full_text_search` is omitted. Set to `false` to embed the text without storing it. The field must then declare `embed` or `sparse_embed`, can't declare `full_text_search`, can't be named in `include_fields`, and can't be searched by text. Fixed at creation. default: true type: boolean embed: $ref: '#/components/schemas/CreateEmbedConfig' sparse_embed: $ref: '#/components/schemas/CreateSparseEmbedConfig' required: - type additionalProperties: false not: not: anyOf: - required: - full_text_search - required: - embed - required: - sparse_embed ReadCapacityDedicatedConfig: description: >- Configuration for dedicated read capacity. See [this guide](https://docs.pinecone.io/guides/index-data/dedicated-read-nodes) for more details on how to configure dedicated read capacity. type: object properties: node_type: description: >- The type of machines to use. Available options: `b1` and `t1`. `t1` includes increased processing power and memory. type: string scaling: description: The type of scaling strategy to use. type: string manual: $ref: '#/components/schemas/ScalingConfigManual' required: - node_type - scaling - manual CreateEmbedConfig: example: dimension: 512 model: llama-text-embed-v2 description: >- Dense embedding configuration for a `string` field. Pinecone embeds the field's text when documents are upserted or updated, and the query text when a search scores the field with an `embed` scoring method. Every key is optional; `{}` selects the default model at its default dimension and metric. Fixed at creation. type: object properties: model: example: llama-text-embed-v2 description: >- The name of a hosted dense embedding model. Defaults to `llama-text-embed-v2`. Refer to the [model guide](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) for available models. type: string dimension: example: 1024 description: >- The dimension of the embedding vectors. Defaults to the model's default dimension. Refer to the [model guide](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) for each model's supported dimensions. type: integer format: int32 minimum: 1 processing_location: example: us description: >- Where the model processes your data. Defaults to the model's default processing location. Supported processing locations depend on the model and your plan. See [Processing locations](https://docs.pinecone.io/guides/index-data/processing-locations). type: string metric: example: cosine description: >- The distance metric used for similarity search. Defaults to the model's default metric. Possible values: `cosine`, `dotproduct`, or `euclidean`. x-enum: - cosine - dotproduct - euclidean type: string write_parameters: example: truncate: END description: >- Model-specific parameters applied when embedding document text, such as `truncate`. Omitted parameters take the model's defaults. type: object read_parameters: example: truncate: END description: >- Model-specific parameters applied when embedding search query text, such as `truncate`. Omitted parameters take the model's defaults. type: object additionalProperties: false CreateSparseEmbedConfig: example: model: pinecone-sparse-english-v0 description: >- Learned-sparse embedding configuration for a `string` field. Pinecone embeds the field's text when documents are upserted or updated, and the query text when a search scores the field with a `sparse_embed` scoring method. Every key is optional; `{}` selects the default model. Fixed at creation. type: object properties: model: example: pinecone-sparse-english-v0 description: >- The name of a hosted sparse embedding model. Defaults to `pinecone-sparse-english-v0`. Refer to the [model guide](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) for available models. type: string write_parameters: example: truncate: END description: >- Model-specific parameters applied when embedding document text, such as `truncate`. Omitted parameters take the model's defaults. type: object read_parameters: example: truncate: END description: >- Model-specific parameters applied when embedding search query text, such as `truncate`. Omitted parameters take the model's defaults. type: object additionalProperties: false ScalingConfigManual: description: The config to use for manual read capacity scaling. type: object properties: replicas: description: >- The number of replicas to use. Replicas duplicate the compute resources and data of an index, allowing higher query throughput and availability. Setting replicas to 0 disables the index but can be used to reduce costs while usage is paused. type: integer format: int32 minimum: 0 shards: description: >- The number of shards to use. Shards determine the storage capacity of an index, with each shard providing 250 GB of storage. type: integer format: int32 minimum: 1 required: - replicas - shards securitySchemes: ApiKeyAuth: type: apiKey in: header name: Api-Key description: >- An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/). ````