Knowledge Base

Endpointhttps://api.neuratel.ai

Knowledge base documents, retrieval, and indexing.

List Knowledge Bases

GET

https://api.neuratel.ai

/v1/knowledge-base

List all knowledge bases for your organization.

Supports filtering with both snake_case and camelCase query parameters.

Date Filters:

createdAtGt / created_at_gt: After this datetime
createdAtLt / created_at_lt: Before this datetime
createdAtGe / created_at_ge: On or after this datetime
createdAtLe / created_at_le: On or before this datetime

Pagination:

limit: Max records (default 100, max 1000)
skip: Offset for pagination
sortOrder: ASC or DESC (default DESC)

Returns documents with their processing status and chunk counts.

List Knowledge Bases › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

sortOrder

string · enum

Sort order: ASC (oldest first) or DESC (newest first). Defaults to DESC.

Sort order for list endpoints

Enum values:

ASC

DESC

Default: DESC

createdAtGt

Filter records created after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

createdAtLt

Filter records created before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

createdAtGe

Filter records created on or after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

createdAtLe

Filter records created on or before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

page

deprecated

(Legacy) Use skip/limit

page_size

deprecated

(Legacy) Use limit

List Knowledge Bases › Responses

Successful Response

Paginated list of knowledge bases. Standardized pagination format: - results: List of knowledge bases - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

GET/v1/knowledge-base

curl --request GET \
  --url https://api.neuratel.ai/v1/knowledge-base

shell

Example Responses

{
  "results": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "name",
      "description": "string",
      "source_type": "url",
      "source_url": "string",
      "source_filename": "string",
      "source_mimetype": "string",
      "size_bytes": 0,
      "chunk_count": 0,
      "status": "pending",
      "progress": 0,
      "error_message": "string",
      "created_by": "string",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "is_active": true
    }
  ],
  "metadata": {
    "count": 100,
    "has_more": true,
    "limit": 100,
    "skip": 0,
    "total": 250
  }
}

json

application/json

Get Knowledge Base

GET

https://api.neuratel.ai

/v1/knowledge-base/{kb_id}

Get a knowledge base by ID.

Get Knowledge Base › path Parameters

kb_id

string · uuid · required

The unique identifier of the knowledge base.

Get Knowledge Base › Responses

Successful Response

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

Update Knowledge Base

PUT

https://api.neuratel.ai

/v1/knowledge-base/{kb_id}

Update a knowledge base's name, description, or content (text documents only).

Update Knowledge Base › path Parameters

kb_id

string · uuid · required

The unique identifier of the knowledge base to update.

Update Knowledge Base › Request Body

Update knowledge base metadata and content.

Updated content for text-based documents

Update Knowledge Base › Responses

Successful Response

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

PUT/v1/knowledge-base/{kb_id}

curl --request PUT \
  --url https://api.neuratel.ai/v1/knowledge-base/:kb_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "description": "string",
  "content": "string"
}
'

shell

Example Request Body

{
  "name": "string",
  "description": "string",
  "content": "string"
}

json

Example Responses

{
  "chunk_count": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "[email protected]",
  "description": "Frequently asked questions",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Company FAQ",
  "organization_id": "550e8400-e29b-41d4-a716-446655440001",
  "size_bytes": 15000,
  "source_type": "url",
  "source_url": "https://example.com/faq",
  "status": "ready",
  "updated_at": "2025-01-15T10:30:00Z"
}

json

application/json

Delete Knowledge Base

DELETE

https://api.neuratel.ai

/v1/knowledge-base/{kb_id}

Delete a knowledge base.

Delete Knowledge Base › path Parameters

kb_id

string · uuid · required

The unique identifier of the knowledge base to delete.

Delete Knowledge Base › Responses

Successful Response

No data returned

Create Knowledge Base From URL

POST

https://api.neuratel.ai

/v1/knowledge-base/from-url

Create a knowledge base from a URL.

Scrapes the web page content and processes it for RAG retrieval. Processing happens asynchronously - check status field for completion.

Create Knowledge Base From URL › Request Body

Create knowledge base from URL (web scraping).

name

string · minLength: 1 · maxLength: 255 · required

Display name

url

string · uri · minLength: 1 · maxLength: 2083 · required

URL to scrape content from

Create Knowledge Base From URL › Responses

Successful Response

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

POST/v1/knowledge-base/from-url

curl --request POST \
  --url https://api.neuratel.ai/v1/knowledge-base/from-url \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Frequently asked questions from our website",
  "name": "Company FAQ",
  "url": "https://example.com/faq"
}
'

shell

Example Request Body

{
  "description": "Frequently asked questions from our website",
  "name": "Company FAQ",
  "url": "https://example.com/faq"
}

json

Example Responses

{
  "chunk_count": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "[email protected]",
  "description": "Frequently asked questions",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Company FAQ",
  "organization_id": "550e8400-e29b-41d4-a716-446655440001",
  "size_bytes": 15000,
  "source_type": "url",
  "source_url": "https://example.com/faq",
  "status": "ready",
  "updated_at": "2025-01-15T10:30:00Z"
}

json

application/json

Create Knowledge Base From Text

POST

https://api.neuratel.ai

/v1/knowledge-base/from-text

Create a knowledge base from direct text input.

Text is immediately chunked and ready for RAG retrieval.

Create Knowledge Base From Text › Request Body

Create knowledge base from direct text input.

name

string · minLength: 1 · maxLength: 255 · required

Display name

content

string · minLength: 1 · maxLength: 500000 · required

Text content (up to 500KB)

Create Knowledge Base From Text › Responses

Successful Response

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

POST/v1/knowledge-base/from-text

curl --request POST \
  --url https://api.neuratel.ai/v1/knowledge-base/from-text \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "This is the product manual content...",
  "description": "Internal product documentation",
  "name": "Product Manual"
}
'

shell

Example Request Body

{
  "content": "This is the product manual content...",
  "description": "Internal product documentation",
  "name": "Product Manual"
}

json

Example Responses

{
  "chunk_count": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "[email protected]",
  "description": "Frequently asked questions",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Company FAQ",
  "organization_id": "550e8400-e29b-41d4-a716-446655440001",
  "size_bytes": 15000,
  "source_type": "url",
  "source_url": "https://example.com/faq",
  "status": "ready",
  "updated_at": "2025-01-15T10:30:00Z"
}

json

application/json

Create Knowledge Base From File

POST

https://api.neuratel.ai

/v1/knowledge-base/from-file

Create a knowledge base from an uploaded file.

Supported formats: txt, md, html, pdf, docx, epub (up to 21MB). Processing happens asynchronously - check status field for completion.

Create Knowledge Base From File › Request Body

Upload a file to create a knowledge base.

name

string · required

Display name for the knowledge base

file

string · binary · required

File to upload (txt, md, html, pdf, docx, epub)

Optional description

Create Knowledge Base From File › Responses

Successful Response

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

POST/v1/knowledge-base/from-file

curl --request POST \
  --url https://api.neuratel.ai/v1/knowledge-base/from-file \
  --header 'Content-Type: multipart/form-data' \
  --form name=name \
  --form description=string \
  --form 'file=<binary>'

shell

Example Request Body

{
  "name": "name",
  "description": "string",
  "file": "<binary>"
}

json

Example Responses

{
  "chunk_count": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "[email protected]",
  "description": "Frequently asked questions",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Company FAQ",
  "organization_id": "550e8400-e29b-41d4-a716-446655440001",
  "size_bytes": 15000,
  "source_type": "url",
  "source_url": "https://example.com/faq",
  "status": "ready",
  "updated_at": "2025-01-15T10:30:00Z"
}

json

application/json

Query Knowledge Bases

POST

https://api.neuratel.ai

/v1/knowledge-base/query

Query knowledge bases for relevant content.

Used by voice agents during calls to retrieve context. Returns top_k most relevant chunks across specified knowledge bases.

Query Knowledge Bases › Request Body

RAG query request from worker.

query

string · minLength: 1 · maxLength: 2000 · required

User's question/query

knowledge_base_ids

string[] · minItems: 1 · required

KB IDs to search

top_k

integer · min: 1 · max: 10

Number of results to return

Default: 3

Query Knowledge Bases › Responses

Successful Response

RAG query response with results.

object[] · required

query

string · required

total_chunks_searched

integer · required

POST/v1/knowledge-base/query

curl --request POST \
  --url https://api.neuratel.ai/v1/knowledge-base/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledge_base_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "query": "What is your return policy?",
  "top_k": 3
}
'

shell

Example Request Body

{
  "knowledge_base_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "query": "What is your return policy?",
  "top_k": 3
}

json

Example Responses

{
  "query": "What is your return policy?",
  "results": [
    {
      "chunk_index": 5,
      "knowledge_base_id": "550e8400-e29b-41d4-a716-446655440000",
      "knowledge_base_name": "Company FAQ",
      "score": 0.85,
      "text": "Our return policy allows returns within 30 days..."
    }
  ],
  "total_chunks_searched": 50
}

json

application/json

Get Agent Knowledge Bases

GET

https://api.neuratel.ai

/v1/knowledge-base/agent/{agent_id}

Get knowledge bases assigned to an agent.

Get Agent Knowledge Bases › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent.

Get Agent Knowledge Bases › Responses

Successful Response

List of knowledge bases assigned to an agent.

agent_id

string · uuid · required

object[] · required

GET/v1/knowledge-base/agent/{agent_id}

curl --request GET \
  --url https://api.neuratel.ai/v1/knowledge-base/agent/:agent_id

shell

Example Responses

{
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "knowledge_bases": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "name",
      "description": "string",
      "source_type": "url",
      "source_url": "string",
      "source_filename": "string",
      "source_mimetype": "string",
      "size_bytes": 0,
      "chunk_count": 0,
      "status": "pending",
      "progress": 0,
      "error_message": "string",
      "created_by": "string",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "is_active": true
    }
  ]
}

json

application/json

Assign Agent Knowledge Bases

PUT

https://api.neuratel.ai

/v1/knowledge-base/agent/{agent_id}

Assign knowledge bases to an agent.

Replaces existing assignments with the provided list. Pass empty list to remove all assignments.

Assign Agent Knowledge Bases › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent.

Assign Agent Knowledge Bases › Request Body

Assign knowledge bases to an agent.

knowledge_base_ids

string[]

KB IDs to assign

Assign Agent Knowledge Bases › Responses

Successful Response

List of knowledge bases assigned to an agent.

agent_id

string · uuid · required

object[] · required

PUT/v1/knowledge-base/agent/{agent_id}

curl --request PUT \
  --url https://api.neuratel.ai/v1/knowledge-base/agent/:agent_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledge_base_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
'

shell

Example Request Body

{
  "knowledge_base_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "knowledge_bases": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "name",
      "description": "string",
      "source_type": "url",
      "source_url": "string",
      "source_filename": "string",
      "source_mimetype": "string",
      "size_bytes": 0,
      "chunk_count": 0,
      "status": "pending",
      "progress": 0,
      "error_message": "string",
      "created_by": "string",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "is_active": true
    }
  ]
}

json

application/json

Billing Authentication