Knowledge API

Upload documents to give your REPLRs specialized knowledge. Documents are chunked, embedded, and used for RAG (Retrieval-Augmented Generation) during conversations.

How RAG Works

Upload

Send a document via multipart/form-data. Supported formats: .txt, .pdf, .md, .csv, .json (max 10 MB).

Chunk

The document is split into overlapping text chunks optimized for semantic search.

Embed

Each chunk is converted into a vector embedding and stored in a vector database.

Retrieve

During a conversation, the user's message is embedded and the most relevant chunks are injected into the REPLR's context.

Endpoints

POST/v1/knowledge/:replr_id/documentsAuth Required

Upload a document to the REPLR's knowledge base. The file is processed asynchronously — poll the document detail endpoint to check when processing completes.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`file`	file	Required	The document file. Supported formats: .txt, .pdf, .md, .csv, .json. Maximum size: 10 MB.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "replr_id": "replr_01j7kx9m3p",
  "filename": "product-faq.pdf",
  "size_bytes": 245780,
  "chunk_count": null,
  "status": "processing",
  "created_at": "2026-03-09T14:22:08Z"
}

Examples

curl -X POST https://api.replr.ai/v1/knowledge/replr_01j7kx9m3p/documents \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@product-faq.pdf"

GET/v1/knowledge/:replr_id/documentsAuth Required

List all documents uploaded to this REPLR's knowledge base. Results are paginated and sorted by creation date (newest first).

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Response

{
  "data": [
    {
      "id": "doc_8f3a1b2c4d5e",
      "filename": "product-faq.pdf",
      "size_bytes": 245780,
      "chunk_count": 34,
      "status": "ready",
      "created_at": "2026-03-09T14:22:08Z"
    },
    {
      "id": "doc_6e9d0c7b8a12",
      "filename": "return-policy.md",
      "size_bytes": 8192,
      "chunk_count": 5,
      "status": "ready",
      "created_at": "2026-03-08T09:15:33Z"
    },
    {
      "id": "doc_3c4f5a6b7d8e",
      "filename": "inventory.csv",
      "size_bytes": 1048576,
      "chunk_count": null,
      "status": "processing",
      "created_at": "2026-03-09T14:30:01Z"
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0
}

GET/v1/knowledge/:replr_id/documents/:doc_idAuth Required

Retrieve a single document with its full processing status and timing details.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.
`doc_id`	string	Required	The unique identifier of the document.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "replr_id": "replr_01j7kx9m3p",
  "filename": "product-faq.pdf",
  "size_bytes": 245780,
  "chunk_count": 34,
  "status": "ready",
  "created_at": "2026-03-09T14:22:08Z",
  "processing": {
    "started_at": "2026-03-09T14:22:09Z",
    "completed_at": "2026-03-09T14:22:18Z",
    "duration_ms": 9012
  }
}

DELETE/v1/knowledge/:replr_id/documents/:doc_idAuth Required

Permanently delete a document and all of its associated vector embeddings. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.
`doc_id`	string	Required	The unique identifier of the document.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "deleted": true
}

POST/v1/knowledge/:replr_id/queryAuth Required

Query the REPLR's knowledge base directly. Useful for testing what context would be retrieved for a given input without starting a conversation.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`query`	string	Required	The natural-language query to search for.
`limit`	integer	Optional	Maximum number of chunks to return. Defaults to 5, maximum 20.

Response

{
  "results": [
    {
      "chunk_id": "chk_a1b2c3d4e5f6",
      "document_id": "doc_8f3a1b2c4d5e",
      "filename": "product-faq.pdf",
      "content": "Our standard return window is 30 days from the date of purchase. Items must be in original packaging and unused condition. Refunds are issued to the original payment method within 5-7 business days.",
      "similarity": 0.92,
      "chunk_index": 12
    },
    {
      "chunk_id": "chk_f6e5d4c3b2a1",
      "document_id": "doc_6e9d0c7b8a12",
      "filename": "return-policy.md",
      "content": "For defective items, we offer a full refund or replacement regardless of the return window. Contact support with your order number and a photo of the defect.",
      "similarity": 0.87,
      "chunk_index": 3
    }
  ],
  "query": "what is the return policy?",
  "total_results": 2
}

Examples

curl -X POST https://api.replr.ai/v1/knowledge/replr_01j7kx9m3p/query \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is the return policy?", "limit": 5 }'

How RAG Works

Upload

Send a document via multipart/form-data. Supported formats: .txt, .pdf, .md, .csv, .json (max 10 MB).

Chunk

The document is split into overlapping text chunks optimized for semantic search.

Embed

Each chunk is converted into a vector embedding and stored in a vector database.

Retrieve

During a conversation, the user's message is embedded and the most relevant chunks are injected into the REPLR's context.

Endpoints

POST/v1/knowledge/:replr_id/documentsAuth Required

Upload a document to the REPLR's knowledge base. The file is processed asynchronously — poll the document detail endpoint to check when processing completes.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`file`	file	Required	The document file. Supported formats: .txt, .pdf, .md, .csv, .json. Maximum size: 10 MB.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "replr_id": "replr_01j7kx9m3p",
  "filename": "product-faq.pdf",
  "size_bytes": 245780,
  "chunk_count": null,
  "status": "processing",
  "created_at": "2026-03-09T14:22:08Z"
}

Examples

curl -X POST https://api.replr.ai/v1/knowledge/replr_01j7kx9m3p/documents \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@product-faq.pdf"

GET/v1/knowledge/:replr_id/documentsAuth Required

List all documents uploaded to this REPLR's knowledge base. Results are paginated and sorted by creation date (newest first).

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Response

{
  "data": [
    {
      "id": "doc_8f3a1b2c4d5e",
      "filename": "product-faq.pdf",
      "size_bytes": 245780,
      "chunk_count": 34,
      "status": "ready",
      "created_at": "2026-03-09T14:22:08Z"
    },
    {
      "id": "doc_6e9d0c7b8a12",
      "filename": "return-policy.md",
      "size_bytes": 8192,
      "chunk_count": 5,
      "status": "ready",
      "created_at": "2026-03-08T09:15:33Z"
    },
    {
      "id": "doc_3c4f5a6b7d8e",
      "filename": "inventory.csv",
      "size_bytes": 1048576,
      "chunk_count": null,
      "status": "processing",
      "created_at": "2026-03-09T14:30:01Z"
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0
}

GET/v1/knowledge/:replr_id/documents/:doc_idAuth Required

Retrieve a single document with its full processing status and timing details.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.
`doc_id`	string	Required	The unique identifier of the document.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "replr_id": "replr_01j7kx9m3p",
  "filename": "product-faq.pdf",
  "size_bytes": 245780,
  "chunk_count": 34,
  "status": "ready",
  "created_at": "2026-03-09T14:22:08Z",
  "processing": {
    "started_at": "2026-03-09T14:22:09Z",
    "completed_at": "2026-03-09T14:22:18Z",
    "duration_ms": 9012
  }
}

DELETE/v1/knowledge/:replr_id/documents/:doc_idAuth Required

Permanently delete a document and all of its associated vector embeddings. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.
`doc_id`	string	Required	The unique identifier of the document.

Response

{
  "id": "doc_8f3a1b2c4d5e",
  "deleted": true
}

POST/v1/knowledge/:replr_id/queryAuth Required

Query the REPLR's knowledge base directly. Useful for testing what context would be retrieved for a given input without starting a conversation.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Required	The unique identifier of the REPLR.

Request Body

Name	Type	Required	Description
`query`	string	Required	The natural-language query to search for.
`limit`	integer	Optional	Maximum number of chunks to return. Defaults to 5, maximum 20.

Response

{
  "results": [
    {
      "chunk_id": "chk_a1b2c3d4e5f6",
      "document_id": "doc_8f3a1b2c4d5e",
      "filename": "product-faq.pdf",
      "content": "Our standard return window is 30 days from the date of purchase. Items must be in original packaging and unused condition. Refunds are issued to the original payment method within 5-7 business days.",
      "similarity": 0.92,
      "chunk_index": 12
    },
    {
      "chunk_id": "chk_f6e5d4c3b2a1",
      "document_id": "doc_6e9d0c7b8a12",
      "filename": "return-policy.md",
      "content": "For defective items, we offer a full refund or replacement regardless of the return window. Contact support with your order number and a photo of the defect.",
      "similarity": 0.87,
      "chunk_index": 3
    }
  ],
  "query": "what is the return policy?",
  "total_results": 2
}

Examples

curl -X POST https://api.replr.ai/v1/knowledge/replr_01j7kx9m3p/query \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is the return policy?", "limit": 5 }'