Skip to content
RAG API

Ingest raw text

POST
/v1/knowledge-bases/{kb_id}/documents/text

Ingest raw text content into a knowledge base without uploading a file. The text is stored as a .txt file and processed through the same ingestion pipeline as file uploads.

Returns immediately with a 202 Accepted response containing the document record in pending status.

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

Request Body required

Section titled “Request Body required ”
object
text
required

Raw text content to ingest

string
>= 1 characters <= 10000000 characters
Example
Machine learning is a subset of artificial intelligence...
name

Optional document name. Defaults to text-{timestamp}.txt.

string
<= 256 characters
Example
ml-notes.txt
metadata

Arbitrary JSON metadata to attach to the document

object
key
additional properties
any
Example
{
  "source": "api",
  "category": "notes"
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Text accepted for 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