Create Knowledge Item

Creates a new knowledge item and queues it for ingestion processing.

HTTP Request

$
POST https://app.resemble.ai/api/v2/knowledge_items

Content-Type

• application/json for URL and text types
• multipart/form-data for document uploads

Request Body

Example Request (URL Type)

$
curl --request POST "https://app.resemble.ai/api/v2/knowledge_items" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  --data '{
>
    "title": "Company FAQ",
>
    "description": "Frequently asked questions from our website",
>
    "source_type": "url",
>
    "url": "https://example.com/faq"
>
  }'

Example Request (Text Type)

$
curl --request POST "https://app.resemble.ai/api/v2/knowledge_items" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  --data '{
>
    "title": "Product Information",
>
    "description": "Core product details",
>
    "source_type": "text",
>
    "raw_text": "Our company sells premium widgets. The Widget Pro costs $99 and includes advanced features like..."
>
  }'

Example Request (Document Type)

$
curl --request POST "https://app.resemble.ai/api/v2/knowledge_items" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -F "title=Product Manual" \
>
  -F "description=Complete product documentation" \
>
  -F "source_type=document" \
>
  -F "document=@/path/to/document.pdf"

Response (Success)

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
5
    "title": "Product FAQ",
6
    "description": "FAQ content",
7
    "source_type": "url",
8
    "status": "pending",
9
    "error_message": null,
10
    "chunk_count": null,
11
    "url": "https://example.com/faq",
12
    "agent_count": 0,
13
    "created_at": "2025-12-01T10:00:00Z",
14
    "updated_at": "2025-12-01T10:00:00Z"
15
  },
16
  "message": "Knowledge item created successfully. Ingestion has been queued."
17
}

Response (Error - Validation)

1
{
2
  "success": false,
3
  "errors": {
4
    "title": [{ "error": "too_long", "message": "Title is too long (maximum is 50 characters)" }],
5
    "url": [{ "error": "invalid_url", "message": "URL must be a valid HTTP or HTTPS URL" }],
6
    "raw_text": [{ "error": "too_long", "message": "Text exceeds maximum length of 10,000 characters" }],
7
    "document": [{ "error": "invalid_type", "message": "Only PDF files are supported" }]
8
  },
9
  "message": "Failed to create knowledge item"
10
}

Response (Error - Limit Reached)

1
{
2
  "success": false,
3
  "errors": {
4
    "base": [{ "error": "limit_reached", "message": "Maximum of 3 knowledge items reached" }]
5
  },
6
  "message": "Failed to create knowledge item"
7
}

Validation Rules

General Validations

• title: Required, max 50 characters
• description: Required, max 200 characters
• source_type: Required, must be one of: document, url, text

URL Type Validations

• url: Required when source_type is url
• Must be a valid HTTP or HTTPS URL
• URL must be accessible for ingestion

Text Type Validations

• raw_text: Required when source_type is text
• Max 10,000 characters

Document Type Validations

• document: Required when source_type is document
• Must be a PDF file
• Max file size: 25MB
• File must be a valid, non-corrupted PDF

Team Limits

• Maximum of 3 knowledge items per team
• Cannot create new items when limit is reached

Processing Flow

After successful creation:

1. Knowledge item is created with status: "pending"
2. Ingestion job is queued automatically
3. Status transitions to processing when job starts
4. Processing includes:
   • Extraction: Extract text from PDF or fetch from URL
   • Chunking: Split content into optimal-sized chunks
   • Embedding: Generate vector embeddings
   • Indexing: Store in search index
5. Status transitions to ready on success or failed on error
6. Poll Get Knowledge Item to monitor progress

Error Codes

Next Steps

After creating a knowledge item:

1. Monitor Status: Poll Get Knowledge Item until status is ready
2. Attach to Agent: Use Attach Knowledge Item to Agent to enable RAG for the agent
3. Configure RAG: Update agent’s search_mode and max_chunks_per_query via Update Agent