Skip to content
Ragex Docs

Replace a document

PUT
/v1/knowledge-bases/{kb_id}/documents/{doc_id}

Replace a document’s content with a new file. The document is re-processed through the full ingestion pipeline (parse, chunk, embed, index), replacing all existing chunks.

The document keeps its ID, metadata, and position in the knowledge base. Only the content and chunks are replaced.

Returns the document record with pending status. Poll until ready or failed.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
kb_id
required
string
/^kb_/
Example
kb_a1b2c3d4e5

Knowledge base ID

doc_id
required
string
/^doc_/
Example
doc_f6g7h8i9j0

Document ID

Request Body required

Section titled “Request Body required ”
object
file
required

The replacement file. Same type restrictions as upload (max 50 MB, 16 supported types).

string format: binary
metadata

Optional JSON string of metadata to replace existing metadata.

string
Example
{"department": "engineering", "version": 3}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Document accepted for re-processing

object
data
required
object
id
required

Document ID (prefixed with doc_)

string
Example
doc_f6g7h8i9j0
kb_id
required

Parent knowledge base ID

string
Example
kb_a1b2c3d4e5
account_id
required

Owning account ID

string
Example
acc_x9y8z7w6v5
name
required

Original file name

string
Example
product-guide.pdf
file_type
required

File extension

string
Example
pdf
file_size_bytes

File size in bytes

integer
nullable
Example
2048576
page_count

Number of pages (for Tier 1 files, set after parsing)

integer
nullable
Example
15
chunk_count
required

Number of chunks generated from this document

integer
Example
34
status
required
string
Allowed values: pending parsing chunking embedding ready failed
error_detail

Error message if status is failed

string
nullable
metadata
required

User-supplied metadata (filterable at search time)

object
key
additional properties
any
Example
{
  "department": "engineering",
  "version": 2
}
storage_path

Internal storage path

string
nullable
Example
acc_x9y8z7w6v5/kb_a1b2c3d4e5/doc_f6g7h8i9j0/product-guide.pdf
created_at
required
string format: date-time
Example
2026-02-10T12:00:00.000Z
updated_at
required
string format: date-time
Example
2026-02-10T12:01:30.000Z

400

Section titled “400 ”

Request validation failed

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "issues": [
        {
          "path": [
            "name"
          ],
          "message": "Required"
        }
      ]
    }
  }
}

401

Section titled “401 ”

Authentication failed or missing

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

404

Section titled “404 ”

Resource not found

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "NOT_FOUND",
    "message": "KnowledgeBase not found: kb_nonexistent"
  }
}

429

Section titled “429 ”

Rate limit or usage limit exceeded

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any