> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Reindex document

POST https://api.getvoxai.com/v1/knowledge/documents/{document_id}/reindex

Reads a document again and indexes it anew, and returns it with `status: indexing`. A web address is read again from the web; a file is read from the original that was stored when it was uploaded. Use it for a document that `failed`, or for an address whose page changed. If the stored original is no longer available the answer is `409 source_unavailable` and you must upload the file again; a document that cannot be re-indexed gives `400 not_reindexable`. With a test key everything is checked but nothing starts: the response has `status: simulated`. Required scope: `knowledge:write`. This operation consumes usage (minutes, SMS or model calls) and is billed to the organization. With a test key (`vx_test_`) it is simulated: nothing real happens and nothing is billed. Requires an `Idempotency-Key` header. NOT retriable: when the operation itself fails with a `429`, a `5xx` or a temporary `409`, the outcome is uncertain and the key becomes "unknown" (the same key gives 409 `idempotency_outcome_unknown`); with no response at all, the same key returns the first outcome or that same 409. After `idempotency_outcome_unknown`, read the state of the resource and retry with a new key only if the operation did not happen. A `429 rate_limited` from the request limit and `409 request_in_progress` come before the operation and leave the key as it is: retry with the same key.

Reference: https://docs.getvoxai.com/api-reference/knowledge-base/knowledge-reindex

## Authentication

- `Authorization` header (bearer token, required) — API key created by an Owner or Admin of the organization. Never in the query string.

## Request

### Path parameters

- `document_id` (string, required) — Id of the document, as returned by `GET /knowledge/documents` or when it was added.

### Headers

- `VoxAI-Version` (enum, optional) — API version for this request; defaults to the version the key is pinned to.
  - Allowed values: `2026-10-01`
- `Idempotency-Key` (string, required) — A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a `4xx` error the same request would always get again (not `429`, and not the temporary `409` codes `request_in_progress`, `caller_has_active_call` and `caller_request_in_progress`: for those, and for a `5xx`, see the note on retrying in the operation); the same key with a different request is refused with `idempotency_key_reused`.

## Response

### 202

Accepted: the work continues in the background.

- `object` ("knowledge_document", required) — Always `knowledge_document`.
- `id` (string, required) — Id of the document: use it in `GET /knowledge/documents/{document_id}` and in the other document operations.
- `name` (string, required) — The name shown for the document: the name given when it was added, or else the file name or the address.
- `type` (enum, required) — `file`: a file that was uploaded. `url`: a web address that was read.
  - Allowed values: `file`, `url`
- `source_url` (string, required, nullable) — The web address the document was read from; `null` for a file.
- `status` (enum, required) — `pending`: registered, indexing not started yet. `indexing`: being read and indexed. `ready`: indexed, the agents can answer from it. `failed`: indexing failed. `simulated`: only with a test key, nothing was added or changed.
  - Allowed values: `pending`, `indexing`, `ready`, `failed`, `simulated`
- `failure` (KnowledgeDocumentsDocumentIdReindexPostResponsesContentApplicationJsonSchemaFailure, required, nullable) — Set when `status` is `failed`. The internal reason is not exposed.
- `chunk_count` (integer, required) — Number of searchable passages the document was split into.
- `indexed_at` (datetime, required, nullable) — When the document was indexed, ISO 8601 UTC; `null` if it was not indexed.
- `needs_review` (boolean, required) — `true` when a person must review the text read from the document in the app: until it is approved the agents do not use it and `POST /knowledge/search` does not return it.
- `reviewed_at` (datetime, required, nullable) — When a person approved the document after review, ISO 8601 UTC; `null` if it was not reviewed.
- `created_at` (datetime, required, nullable) — When the document was added, ISO 8601 UTC.
- `simulated` (boolean, required) — `true` with a test key: the request was checked and nothing was added or changed.

## Errors

### 400 Bad Request Error

Possible errors: * `invalid_api_version`: The `VoxAI-Version` header names a version that does not exist. Use one of the versions listed in the `VoxAI-Version` parameter, or omit the header to use the version the key is pinned to. * `invalid_request`: The path, query or body does not match the schema of the operation: a missing or unknown field, a wrong type, a value out of range. Fix the request. `details` lists each problem as `{ location, path, message }`: `location` is `params`, `query` or `body` and `path` points to the field. * `not_reindexable`: This document cannot be re-indexed (it has no stored source). Delete it and add it again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 401 Unauthorized Error

Possible errors: - `invalid_api_key`: The `Authorization` header is missing, malformed, or carries a key that does not exist, was revoked or has expired. Send `Authorization: Bearer vx_live_…` (or `vx_test_…`) with an active key. Create a new key in the app if this one expired.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 403 Forbidden Error

Possible errors: - `feature_not_available`: The plan of the organization does not include the API, or the feature this operation needs. Upgrade the plan in the app. Reads and deletions stay available after a downgrade. - `insufficient_scope`: The key does not have the scope this operation requires (written in the description of the operation). Create a key with the required scope (an Owner or Admin can do it in the app), or ask for the scope to be added. - `ip_not_allowed`: The key has an IP allow-list and the request comes from an address that is not on it. Call from an allowed address, or add this address to the key in the app. - `organization_suspended`: The organization that owns the key is suspended. Contact the organization Owner: nothing can be done through the API until the organization is active again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 404 Not Found Error

Possible errors: - `not_found`: The resource does not exist, or it belongs to another organization: the two cases give the same answer on purpose. Check the id. Ids come from the list operations of the same organization.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 409 Conflict Error

Possible errors: * `idempotency_outcome_unknown`: A previous request with this `Idempotency-Key` failed with a `429`, a `5xx` or a temporary `409` inside a NOT retriable operation, or was interrupted with no response, so its outcome is not known and it is never run again with the same key. Read the state of the resource (for example `GET /outbound-calls/{outbound_call_id}` or the list) and retry with a NEW key only if the operation did not happen. * `request_in_progress`: A request with the same `Idempotency-Key` is still running. Wait a few seconds and retry with the same key: you will get the outcome of the first request. * `source_unavailable`: The original file of the document is no longer stored, so it cannot be read again. Delete the document and upload the file again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 422 Unprocessable Entity Error

Possible errors: - `idempotency_key_reused`: The same `Idempotency-Key` was already used in the last 24 hours with a different request (other operation, path or body). Use a new key for a new request. Reuse a key only to repeat exactly the same request.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 429 Too Many Requests Error

Possible errors: - `rate_limited`: Too many requests: over the per-minute limit of this key or of the whole organization (see `rate_limits` in `GET /me`), or over a limit of the operation itself, such as the hourly limit on webhook tests and resends. Wait for the number of seconds in the `Retry-After` header, then retry. Spread requests over time.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 500 Internal Server Error

Possible errors: - `internal_error`: An unexpected error on our side. Retry once after a few seconds. For writes marked as retriable, retry with the same `Idempotency-Key`, so the operation is never done twice; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen. If it persists, contact support with the `requestId`.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 503 Service Unavailable Error

Possible errors: - `api_not_configured`: The API is not enabled on this service. Contact support. - `knowledge_indexing_unavailable`: Indexing is not available on the service right now, so no document can be added or re-indexed. Nothing was saved. Retry later. For a re-index, retry with a NEW `Idempotency-Key`. If it persists, contact support with the `requestId`. - `service_unavailable`: A component the operation depends on is temporarily unavailable. Retry after a few seconds. For writes marked as retriable, use the same `Idempotency-Key`; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

## Types

### KnowledgeDocumentsDocumentIdReindexPostResponsesContentApplicationJsonSchemaFailure

Set when `status` is `failed`. The internal reason is not exposed.

- `code` ("indexing_failed", required) — Always `indexing_failed`: the internal reason is not exposed.

## Examples

**Response**

```json
{
  "object": "knowledge_document",
  "id": "e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57",
  "name": "Studio Rossi FAQ",
  "type": "url",
  "source_url": "https://www.example.com/faq",
  "status": "indexing",
  "failure": null,
  "chunk_count": 0,
  "indexed_at": null,
  "needs_review": false,
  "reviewed_at": null,
  "created_at": "2026-11-16T11:20:05Z",
  "simulated": false
}
```

**SDK Code**

```python
import requests

url = "https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex"

headers = {
    "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex")
  .header("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Idempotency-Key' => '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getvoxai.com/v1/knowledge/documents/e29b7d04-1c5a-4f38-a6d2-8b0e3c9f1a57/reindex")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```