RAG

Build a knowledge base from documents and URLs to power AI-assisted conversations with Retrieval-Augmented Generation. RAGs enable your AI agents to answer questions using your own content — product documentation, FAQs, support articles — instead of relying solely on the LLM’s training data.

API Reference: RAG endpoints

Overview

Note

AI Context

• Complexity: Low

• Cost: Free for CRUD operations. Chargeable for document processing (parsing, chunking, and embedding consume credits).

• Async: Yes. Document processing runs asynchronously after creation. Check status via GET https://api.voipbin.net/v1.0/rag-documents/{id}.

A RAG (Retrieval-Augmented Generation) is a knowledge base that lets your AI agents answer questions using your own content. Instead of relying solely on the LLM’s training data, the AI retrieves relevant passages from your uploaded documents and URLs at query time, grounding its responses in your authoritative content.

Note

AI Implementation Hint

A RAG is a configuration resource, not a runtime entity. You create a RAG via POST /rags, add documents to it via POST /rag-documents, then reference the RAG’s id in an AI configuration (rag_id field on POST /ais or PUT /ais/{id}). The RAG itself does not answer questions — it provides the knowledge base that the AI agent queries during conversations.

How it works

Architecture

+-----------------------------------------------------------------------+
|                     RAG Architecture                                  |
+-----------------------------------------------------------------------+

1. SETUP (design-time)

   User creates a RAG
   +---------------------+
   |       RAG            |
   | name: "Product KB"   |
   | id: <rag-uuid>       |
   +----------+----------+
              |
              | Add documents
              v
   +---------------------+     +---------------------+
   |   Document A         |     |   Document B         |
   |   type: url          |     |   type: uploaded      |
   |   source_url: https: |     |   storage_file_id:    |
   |     //docs.example.. |     |     <file-uuid>       |
   +----------+----------+     +----------+----------+
              |                            |
              v                            v
   +-------------------------------------------------------+
   |              Document Processing Pipeline              |
   |                                                        |
   |   1. Fetch/read content                                |
   |   2. Parse into text                                   |
   |   3. Chunk into passages                               |
   |   4. Generate embeddings (vectorize)                   |
   |   5. Store chunks in vector database                   |
   +-------------------------------------------------------+

2. RUNTIME (during a conversation)

   Caller asks a question
        |
        v
   AI extracts query from conversation
        |
        v
   Query embedding generated
        |
        v
   Vector DB searched for similar chunks
        |
        v
   Top-k relevant passages retrieved
        |
        v
   Passages injected into LLM context
        |
        v
   AI responds with grounded answer

Document Processing

When you add a document to a RAG, the system processes it asynchronously through a pipeline:

1. Fetch — For url documents, the system fetches the content from source_url. For uploaded documents, it reads the file from storage (storage_file_id).

2. Parse — The raw content is converted to plain text. Supported formats include PDF, HTML, plain text, and common document formats.

3. Chunk — The text is split into overlapping passages (chunks) optimized for retrieval. Chunk sizes are tuned to balance context completeness with retrieval precision.

4. Embed — Each chunk is converted to a vector embedding using an embedding model.

5. Store — The chunk text and its embedding are stored in a vector database, indexed by the RAG’s id.

Document Lifecycle

Documents progress through a status lifecycle during processing:

• pending — Document created but processing has not started yet.

• processing — Document is being fetched, parsed, chunked, and embedded.

• ready — Processing complete. Chunks are stored and available for retrieval.

• error — Processing failed. Check status_message for the error reason.

+-----------------------------------------------------------------------+
|                     Document Status Lifecycle                         |
+-----------------------------------------------------------------------+

Created via POST
     |
     v
+-----------+       +--------------+       +-----------+
| pending   | ----> | processing   | ----> |   ready   |
+-----------+       +--------------+       +-----------+
                          |
                          | (failure)
                          v
                    +-----------+
                    |   error   |
                    +-----------+

Note

AI Implementation Hint

After creating a document via POST /rag-documents, poll GET /rag-documents/{id} to check the status field. Do not assume the document is ready for queries immediately — processing can take seconds to minutes depending on document size. Only documents with status: ready contribute to RAG query results.

Use Cases

• Customer support knowledge base — Upload FAQ documents, support articles, and troubleshooting guides. The AI agent retrieves relevant answers during live support calls.

• Product documentation — Add product manuals, API docs, and feature guides. The AI answers customer questions with accurate, up-to-date product information.

• Internal training — Build knowledge bases from training materials, SOPs, and policy documents for AI-assisted employee onboarding calls.

• Sales enablement — Upload pricing sheets, competitive analysis, and product comparisons. The AI assists sales agents with accurate data during prospect calls.

Related Documentation

• AI Configuration — How AI voice conversations work and how to reference a RAG in an AI configuration

• Team — Multi-agent conversations that can leverage RAG-backed AI members

• Storage — File storage for uploaded documents (storage_file_id)

RAG

RAG

{
    "id": "<string>",
    "customer_id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>"
}

• id (UUID): The RAG’s unique identifier. Returned when creating a RAG via POST /rags or when listing RAGs via GET /rags.

• customer_id (UUID): The customer that owns this RAG. Obtained from the id field of GET /customer.

• name (String, Required): A human-readable name for the knowledge base (e.g., "Product Documentation KB").

• description (String, Optional): A description of the RAG’s purpose or the type of content it contains (e.g., "Contains all customer-facing product documentation and FAQs").

• tm_create (String, ISO 8601): Timestamp when the RAG was created.

• tm_update (String, ISO 8601): Timestamp when the RAG was last updated.

Note

AI Implementation Hint

The name and description fields are for organizational purposes only — they do not affect how the RAG retrieves or ranks content. Use descriptive names to help identify knowledge bases when you have multiple RAGs (e.g., "Support KB - English" vs "Support KB - Korean").

Example

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Product Documentation KB",
    "description": "Knowledge base containing product manuals, API docs, and FAQ articles",
    "tm_create": "2026-03-15 09:00:00.000000",
    "tm_update": "2026-03-15 09:00:00.000000"
}

Document

Document

{
    "id": "<string>",
    "customer_id": "<string>",
    "rag_id": "<string>",
    "name": "<string>",
    "doc_type": "<string>",
    "storage_file_id": "<string>",
    "source_url": "<string>",
    "status": "<string>",
    "status_message": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>"
}

• id (UUID): The document’s unique identifier. Returned when creating a document via POST /rag-documents or when listing documents via GET /rag-documents.

• customer_id (UUID): The customer that owns this document. Obtained from the id field of GET /customer.

• rag_id (UUID, Required): The RAG knowledge base this document belongs to. Obtained from the id field of POST /rags or GET /rags.

• name (String, Required): A human-readable name for the document (e.g., "Product API Reference v2.1").

• doc_type (String enum, Required): The type of document source. Determines which additional field is required. One of:

  • uploaded — A file uploaded to VoIPBIN storage. Requires storage_file_id.

  • url — A web page or publicly accessible document URL. Requires source_url.

  • platform — Content generated by or sourced from the VoIPBIN platform itself.

  • generated — Content automatically generated by the system (e.g., summaries, extracted metadata).

• storage_file_id (UUID, Optional): The storage file that contains the document content. Obtained from the id field of POST /storage-files or GET /storage-files. Required when doc_type is uploaded. Ignored for other doc_type values.

• source_url (String URI, Optional): The URL to fetch document content from. Must be a publicly accessible HTTP or HTTPS URL. Required when doc_type is url. Ignored for other doc_type values.

• status (String enum): The current processing status of the document. One of:

  • pending — Document created but processing has not started yet.

  • processing — Document is being fetched, parsed, chunked, and embedded.

  • ready — Processing complete. Chunks are stored and available for RAG queries.

  • error — Processing failed. Check status_message for the error details.

• status_message (String): Human-readable message providing details about the current status. Typically empty for pending and ready states. Contains error details when status is error (e.g., "Failed to fetch URL: connection timeout").

• tm_create (String, ISO 8601): Timestamp when the document was created.

• tm_update (String, ISO 8601): Timestamp when the document was last updated.

Note

AI Implementation Hint

The doc_type field determines which source field to populate:

• If doc_type is uploaded, set storage_file_id to the UUID of an uploaded file. Upload the file first via POST /storage-files, then use the returned id.

• If doc_type is url, set source_url to the full URL (e.g., "https://docs.example.com/faq").

• Setting both storage_file_id and source_url is allowed but only the field matching doc_type will be used.

Note

AI Implementation Hint

Documents are immutable after creation — there is no PUT /rag-documents/{id} endpoint. If the source content changes (e.g., a web page is updated), delete the old document via DELETE /rag-documents/{id} and create a new one via POST /rag-documents. This ensures the vector database stays consistent with the source content.

Example

URL document:

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product FAQ Page",
    "doc_type": "url",
    "storage_file_id": "00000000-0000-0000-0000-000000000000",
    "source_url": "https://docs.example.com/faq",
    "status": "ready",
    "status_message": "",
    "tm_create": "2026-03-15 09:10:00.000000",
    "tm_update": "2026-03-15 09:12:30.000000"
}

Uploaded document:

{
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product Manual v2.1 (PDF)",
    "doc_type": "uploaded",
    "storage_file_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "source_url": "",
    "status": "processing",
    "status_message": "",
    "tm_create": "2026-03-15 09:15:00.000000",
    "tm_update": "2026-03-15 09:15:05.000000"
}

Tutorial

Before creating a RAG, you need:

• A valid authentication token (String). Obtain via POST /auth/login or use an accesskey from GET /accesskeys.

• (Optional) A storage file ID (UUID) if you plan to upload documents. Upload files first via POST /storage-files.

Note

AI Implementation Hint

A RAG knowledge base is most useful when connected to an AI agent. After completing this tutorial, reference the RAG’s id in an AI configuration via POST /ais or PUT /ais/{id} (set the rag_id field). The AI agent will then query this knowledge base during conversations.

Step 1: Create a RAG

Create a new RAG knowledge base to hold your documents.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/rags?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "Product Documentation KB",
        "description": "Knowledge base for product manuals, API docs, and FAQ articles"
    }'

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",   // Save this as rag_id
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Product Documentation KB",
    "description": "Knowledge base for product manuals, API docs, and FAQ articles",
    "tm_create": "2026-03-15 09:00:00.000000",
    "tm_update": "2026-03-15 09:00:00.000000"
}

Step 2: Add a URL Document

Add a web page to the RAG. The system will fetch the URL, parse the content, and create searchable chunks.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/rag-documents?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Product FAQ Page",
        "doc_type": "url",
        "source_url": "https://docs.example.com/faq"
    }'

Response:

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",   // Save this as document_id
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product FAQ Page",
    "doc_type": "url",
    "storage_file_id": "00000000-0000-0000-0000-000000000000",
    "source_url": "https://docs.example.com/faq",
    "status": "pending",                              // Processing has not started yet
    "status_message": "",
    "tm_create": "2026-03-15 09:10:00.000000",
    "tm_update": "2026-03-15 09:10:00.000000"
}

Step 3: Add an Uploaded Document

Add a file that you previously uploaded to VoIPBIN storage. Upload the file first via POST /storage-files, then reference its id as storage_file_id.

$ curl --location --request POST 'https://api.voipbin.net/v1.0/rag-documents?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Product Manual v2.1 (PDF)",
        "doc_type": "uploaded",
        "storage_file_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
    }'

Response:

{
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",   // Save this as uploaded_document_id
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product Manual v2.1 (PDF)",
    "doc_type": "uploaded",
    "storage_file_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "source_url": "",
    "status": "pending",
    "status_message": "",
    "tm_create": "2026-03-15 09:15:00.000000",
    "tm_update": "2026-03-15 09:15:00.000000"
}

Step 4: Check Document Status

Documents are processed asynchronously. Poll the document endpoint to check processing progress.

$ curl --location --request GET 'https://api.voipbin.net/v1.0/rag-documents/b2c3d4e5-f6a7-8901-bcde-f23456789012?token=<YOUR_AUTH_TOKEN>'

Response (processing complete):

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product FAQ Page",
    "doc_type": "url",
    "storage_file_id": "00000000-0000-0000-0000-000000000000",
    "source_url": "https://docs.example.com/faq",
    "status": "ready",                                // Processing complete
    "status_message": "",
    "tm_create": "2026-03-15 09:10:00.000000",
    "tm_update": "2026-03-15 09:12:30.000000"
}

Note

AI Implementation Hint

Poll with a reasonable interval (e.g., every 5 seconds). Processing time depends on document size: a short FAQ page may complete in seconds, while a large PDF manual may take several minutes. Only documents with status: ready are included in RAG query results. Documents with status: error should be investigated and re-created.

Step 5: List Documents by RAG

List all documents belonging to a specific RAG by filtering on rag_id.

$ curl --location --request GET 'https://api.voipbin.net/v1.0/rag-documents?rag_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&token=<YOUR_AUTH_TOKEN>'

Response:

{
    "result": [
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Product FAQ Page",
            "doc_type": "url",
            "storage_file_id": "00000000-0000-0000-0000-000000000000",
            "source_url": "https://docs.example.com/faq",
            "status": "ready",
            "status_message": "",
            "tm_create": "2026-03-15 09:10:00.000000",
            "tm_update": "2026-03-15 09:12:30.000000"
        },
        {
            "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Product Manual v2.1 (PDF)",
            "doc_type": "uploaded",
            "storage_file_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
            "source_url": "",
            "status": "ready",
            "status_message": "",
            "tm_create": "2026-03-15 09:15:00.000000",
            "tm_update": "2026-03-15 09:17:45.000000"
        }
    ],
    "next_page_token": ""
}

Step 6: Update RAG

Update the RAG’s name or description.

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/rags/a1b2c3d4-e5f6-7890-abcd-ef1234567890?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "Product Documentation KB (v2)",
        "description": "Updated knowledge base with product manuals, API docs, FAQ articles, and troubleshooting guides"
    }'

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Product Documentation KB (v2)",
    "description": "Updated knowledge base with product manuals, API docs, FAQ articles, and troubleshooting guides",
    "tm_create": "2026-03-15 09:00:00.000000",
    "tm_update": "2026-03-15 10:00:00.000000"
}

Step 7: Delete a Document

Delete a single document from the RAG. This removes the document and all its chunks from the vector database.

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/rag-documents/b2c3d4e5-f6a7-8901-bcde-f23456789012?token=<YOUR_AUTH_TOKEN>'

Response:

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product FAQ Page",
    "doc_type": "url",
    "storage_file_id": "00000000-0000-0000-0000-000000000000",
    "source_url": "https://docs.example.com/faq",
    "status": "ready",
    "status_message": "",
    "tm_create": "2026-03-15 09:10:00.000000",
    "tm_update": "2026-03-15 09:12:30.000000"
}

Note

AI Implementation Hint

Deleting a document does not affect the RAG itself or other documents in the RAG. The deleted document’s chunks are removed from the vector database, so subsequent RAG queries will no longer return results from that document. The storage file (if doc_type is uploaded) is NOT deleted — manage storage files separately via DELETE /storage-files/{id}.

Step 8: Delete a RAG

Delete a RAG and all its documents. This is a cascade delete — all documents belonging to the RAG are deleted along with their vector database chunks.

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/rags/a1b2c3d4-e5f6-7890-abcd-ef1234567890?token=<YOUR_AUTH_TOKEN>'

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "name": "Product Documentation KB (v2)",
    "description": "Updated knowledge base with product manuals, API docs, FAQ articles, and troubleshooting guides",
    "tm_create": "2026-03-15 09:00:00.000000",
    "tm_update": "2026-03-15 10:00:00.000000"
}

Note

AI Implementation Hint

Deleting a RAG performs a cascade delete — all documents in the RAG are automatically deleted, and their chunks are removed from the vector database. If any AI configuration references this RAG (via rag_id), the AI will no longer have access to this knowledge base. Update or remove the rag_id from affected AI configurations via PUT /ais/{id} to avoid runtime errors.

Best Practices

Knowledge Base Design:

• Create separate RAGs for distinct knowledge domains (e.g., one for product docs, another for internal policies). This keeps retrieval focused and relevant.

• Use descriptive name and description fields to make RAGs easy to identify when managing multiple knowledge bases.

• Keep documents focused on a single topic when possible. A 5-page FAQ document retrieves more precisely than a 500-page monolithic manual.

Document Management:

• Check document status before relying on a RAG for AI conversations. Documents with status: pending or status: processing are not yet available for queries.

• When source content changes, delete the old document and create a new one. Documents are immutable — there is no update endpoint.

• For url documents, ensure the URL is publicly accessible. Private URLs behind authentication will fail during the fetch step.

• For uploaded documents, upload the file to storage first via POST /storage-files, verify the upload succeeded, then create the document.

Performance:

• Smaller, well-structured documents produce better retrieval results than large unstructured documents.

• Add multiple targeted documents rather than one massive document covering everything.

Troubleshooting

• 400 Bad Request:

  • Cause: Missing required field (e.g., name, rag_id, or doc_type).

  • Fix: Include all required fields in the request body. Verify field names match the API schema exactly.

• 400 Bad Request:

  • Cause: doc_type is uploaded but storage_file_id is missing or set to the zero UUID.

  • Fix: Upload a file via POST /storage-files first, then set storage_file_id to the returned id.

• 400 Bad Request:

  • Cause: doc_type is url but source_url is missing or not a valid URL.

  • Fix: Provide a fully qualified URL starting with http:// or https://.

• 404 Not Found:

  • Cause: The RAG or document UUID does not exist or belongs to a different customer.

  • Fix: Verify the UUID was obtained from a recent GET /rags or GET /rag-documents call.

• 404 Not Found:

  • Cause: The rag_id specified when creating a document does not exist.

  • Fix: Create the RAG first via POST /rags, then use the returned id as rag_id.

• Document stuck in ``pending`` or ``processing``:

  • Cause: Processing pipeline delay or the document source is temporarily unavailable.

  • Fix: Wait and retry GET /rag-documents/{id}. If the status does not change after several minutes, delete and re-create the document.

• Document status is ``error``:

  • Cause: The system failed to fetch, parse, or process the document content. Common reasons include unreachable URLs, unsupported file formats, or empty documents.

  • Fix: Check the status_message field for details. Fix the underlying issue (e.g., make the URL accessible, use a supported format) and create a new document.