Starts a reindex job that populates a new generation by copying documents from an existing generation of the same index inside the engine. The request returns immediately with the job record; the job runs in the background on the node holding the index.
The target must specify a generation by name, must already exist, must be empty, and must not be the live generation. The source generation must have a primary key and keep document sources, and the primary keys of source and target must share a field name and type. If the target does not meet these requirements, the server returns 400.
The job automatically promotes the target generation once it catches up with changes, unless the request specifies "promote": "manual". With manual promotion, the job pauses in the ready phase and keeps the target caught up until actions/promote on the target finishes the job.
Because promoting changes what the index answers for, a request that leaves promotion automatic also needs indexes.promote on the target and is refused with 403 without it. A request specifying "promote": "manual" needs only indexes.reindex.
An index can run at most one reindex job at a time. A finished job's record remains readable until a new job replaces it. Read the record with GET /v1alpha1/admin/reindexes/{name}, which the Location header of the response names.
Path parameters
namestringrequired
The generation to fill, as index@generation. It must already exist, be empty, and not be the live generation.
Body
ReindexRequestOptional
Configuration for a reindex job. Both fields are optional; an empty body reads from the live generation and promotes automatically.
fromstring
The generation to read documents from: an index name, or a generation such as products@1. Must belong to the same index as the target. Defaults to the live generation.
Example
"products@1"
promotestring
The promotion mode. auto (default) automatically promotes the target generation once it catches up with changes. manual pauses the job in the ready phase and keeps the target caught up until you manually promote it.
Default
"auto"
Values
"auto", "manual"
Responses
202
A reindex job was started and runs asynchronously. The Location header names the status endpoint of the job.
The id of the job, minted when it was accepted. Tells one job of an index from the one that replaced it. null on a record an earlier version wrote.
Example
"6f1c2a9d8b3e4c05"
indexstring
The name of the index.
Example
"products"
targetstring
The generation being populated, formatted as index@generation.
Example
"products@2"
sourcestring
The generation providing the source documents.
Example
"products@1"
phasestring
The current phase of the job. pending: accepted and waiting for a concurrency slot on the node. copying: streaming documents from the source to the target in primary key order. replaying: copying documents that changed in the source while the copy ran. ready: used only with promote: manual, caught up and waiting for manual promotion, while continuing to catch up periodically. promoting: holding writes for the final drain and promotion. done: completed and promoted successfully. failed: stopped before promotion due to an error, indicated by error. cancelled: stopped before completion in response to a cancellation request.
The configured promote mode. auto automatically promotes the target generation once it catches up with changes. manual pauses the job in the ready phase and keeps the target caught up until you manually promote it.
Values
"auto", "manual"
Example
"auto"
documentsCopiedinteger
The number of confirmed documents copied to the target.
Format
int64
Example
125000
sourceDocumentsinteger
The document count of the source generation when the copy started.
Format
int64
Example
2400000
backloginteger
The number of changed documents waiting to be replayed when the record was last written.
Format
int64
Example
4100
errorstring
The error message if the job failed, or null.
startedBystring
The id of the principal whose request started the job: the id of a key, or the name of a configured principal such as root. null on a record an earlier version wrote.
Example
"3f9a1c7e2b8d4650"
nodestring
The name of the node running the job, as the indexer listing names it, or the node that ended it. A job resumed on another node after a failover names that node from its next checkpoint on. null on a record an earlier version wrote.
Example
"node-a-7f21"
startedAtstring
The timestamp when the job started.
Example
"2026-08-28T10:15:30Z"
updatedAtstring
The timestamp when the job record was last updated.
Example
"2026-08-28T10:16:02Z"
finishedAtstring
The timestamp when the job reached done, failed or cancelled, or null while it runs.
Example
"2026-08-28T10:41:17Z"
freshnessstring
A freshness token for the state the promotion of the target landed in. Present once the job reaches done, and null before that. Pass it as freshness.atLeast on a search, and the search is answered from the target generation whichever node it lands on. Opaque; pass it back unchanged. See Freshness.
Example
"AQoIcHJvZHVjdHMSATI"
400
The target does not specify a generation by name, does not exist, is not empty, is the live generation, or the source and target primary keys do not match.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The source generation keeps no copy of the documents to read them back from. A reindex reads the stored copies.
401
The request carries no credential this node accepts. Absent, malformed, unknown and lapsed keys are all answered alike, so a refusal cannot be used to find out which keys exist. The response carries WWW-Authenticate: Bearer.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The request carries no credential this node accepts.
403
The API key does not have the indexes.reindex permission.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The key is accepted but does not hold the `indexes.reindex` permission.
404
The specified index or generation does not exist, or the caller key lacks permissions on the index.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
No index or generation has this name, or the key holds no grant covering it.
409
The job could not be started.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
No node is available to write the index. Send the request again once one is.
502
The request was forwarded to the index writer and the writer did not respond.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
An API key sent as a bearer token, such as Authorization: Bearer exok_4ff6b760264c1918_ePQcdT1O9HSATZoXfDbT8hhHGsP9VpZH. A key carries grants that pair permissions with index patterns; the permission each endpoint needs is named beside it. Nodes running with EXOFIND_AUTH_MODE=none accept requests without a credential, and a node with EXOFIND_AUTH_ANONYMOUS_KEY set serves requests that carry none with the permissions of that key.
Exofind is built by Level Four AB and is available under the Apache License 2.0.