Update a training file

PATCH/v2/training_data/files/{id}

Renames a training file, replaces content, or sets externalId / source. Indexing is attempted before returning when content is available. Check status and indexStatus; HTTP success alone does not establish search readiness. Serialize updates to a source identity in your pipeline.

Path ParametersExpand Collapse

id: string

The training file ID

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-08-19.orbit" or "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-08-19.orbit"

"2026-01-01.nova"

"2025-12-12.clover"

Body ParametersJSONExpand Collapse

content: optional string

Replacement text/markdown. Indexing is attempted before returning; check indexStatus.

maxLength2000000

externalId: optional string

Your own identifier for this entry (unique per workspace).

minLength1

maxLength255

name: optional string

New display name

minLength1

maxLength255

source: optional string

Free-form label for the pipeline or system this entry came from. Filter lists by it to review or sweep everything from one source.

minLength1

maxLength100

ReturnsExpand Collapse

TrainingFile object { id, characterCount, contentHash, 15 more }

id: string

Training file ID

characterCount: number

Characters of extracted text

contentHash: string

SHA-256 (hex) of the stored source: for inline text and content edits the trimmed text, for uploads and URLs the original bytes. Compare it with your own hash to detect changes without downloading content.

contentPreview: string

First 200 characters of the extracted text

createdAt: string

ISO timestamp of the upload

externalId: string

Your own identifier for this file, if one was set

fileSize: number

Size of the originally uploaded source in bytes (unchanged by content edits)

indexStatus: "pending" or "indexed" or "failed"

Whether the content is searchable by the AI agent. pending while indexing, indexed when the AI agent can use it, failed if indexing failed (the content is stored and indexing is retried hourly).

One of the following:

"pending"

"indexed"

"failed"

mimeType: string

MIME type of the originally uploaded source

name: string

File name shown in the dashboard

object: "training_file"

Object type identifier

processingError: string

Conversion error message when status is failed

source: string

Pipeline label, if one was set

status: "processing" or "completed" or "failed"

processing while the file is being converted to text, completed once the content is stored, failed if conversion failed (see processingError).

One of the following:

"processing"

"completed"

"failed"

updatedAt: string

ISO timestamp of the last change

wordCount: number

Words of extracted text

content: optional string

Full extracted text (markdown). Returned when retrieving or updating a single file; omitted from list and create responses.

outcome: optional "created" or "updated" or "unchanged"

On create and update responses: created, updated (same externalId or same name and bytes, content replaced and re-indexed), or unchanged (identical content, nothing done). Absent on reads.

One of the following:

"created"

"updated"

"unchanged"

Update a training file

curl https://do.featurebase.app/v2/training_data/files/$ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "content": "# Refund policy\\n\\nCustomers can request a refund within 60 days of purchase…",
          "externalId": "kb-article-1842",
          "name": "refund-policy-v2.md",
          "source": "resolved-conversations"
        }'

{
  "id": "67ec1234abcd5678ef901234",
  "characterCount": 12840,
  "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "contentPreview": "# Refund policy\n\nCustomers can request a refund within 30 days…",
  "createdAt": "2026-09-03T10:15:00.000Z",
  "externalId": "kb-article-1842",
  "fileSize": 48213,
  "indexStatus": "indexed",
  "mimeType": "application/pdf",
  "name": "refund-policy.pdf",
  "object": "training_file",
  "processingError": null,
  "source": "resolved-conversations",
  "status": "completed",
  "updatedAt": "2026-09-03T10:15:30.000Z",
  "wordCount": 2130,
  "content": "# Refund policy\n\nCustomers can request a refund within 30 days of purchase…",
  "outcome": "created"
}

Returns Examples

{
  "id": "67ec1234abcd5678ef901234",
  "characterCount": 12840,
  "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "contentPreview": "# Refund policy\n\nCustomers can request a refund within 30 days…",
  "createdAt": "2026-09-03T10:15:00.000Z",
  "externalId": "kb-article-1842",
  "fileSize": 48213,
  "indexStatus": "indexed",
  "mimeType": "application/pdf",
  "name": "refund-policy.pdf",
  "object": "training_file",
  "processingError": null,
  "source": "resolved-conversations",
  "status": "completed",
  "updatedAt": "2026-09-03T10:15:30.000Z",
  "wordCount": 2130,
  "content": "# Refund policy\n\nCustomers can request a refund within 30 days of purchase…",
  "outcome": "created"
}