Real-Time AgentsAgent Knowledge Base

Detach Knowledge Item from Agent

Removes a knowledge item from an agent. The knowledge item itself is not deleted and remains available for other agents.

HTTP Request

$DELETE https://app.resemble.ai/api/v2/agents/{agent_uuid}/knowledge_items/{knowledge_item_uuid}

URL Parameters

ParameterTypeDescription
agent_uuidstringThe UUID of the agent
knowledge_item_uuidstringThe UUID of the knowledge item to detach

Example Request

$curl --request DELETE "https://app.resemble.ai/api/v2/agents/agent-uuid-123/knowledge_items/550e8400-e29b-41d4-a716-446655440000" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  -H "Content-Type: application/json"

Response (Success)

1{
2  "success": true,
3  "items": [],
4  "message": "Knowledge item detached successfully"
5}

Response (Success with Remaining Items)

1{
2  "success": true,
3  "items": [
4    {
5      "uuid": "660e8400-e29b-41d4-a716-446655440001",
6      "title": "Product Manual",
7      "description": "Complete product documentation",
8      "source_type": "document",
9      "status": "ready",
10      "error_message": null,
11      "chunk_count": 42,
12      "document_url": "https://storage.example.com/signed-url",
13      "document_filename": "manual.pdf",
14      "created_at": "2025-12-01T09:00:00Z",
15      "updated_at": "2025-12-01T09:15:00Z"
16    }
17  ],
18  "message": "Knowledge item detached successfully"
19}

Error Response (Not Attached)

1{
2  "success": false,
3  "errors": {
4    "knowledge_item_uuid": [{ "error": "not_attached", "message": "Knowledge item is not attached to this agent" }]
5  },
6  "message": "Failed to detach knowledge item"
7}

Error Response (Not Found)

1{
2  "success": false,
3  "errors": {
4    "base": ["Agent or knowledge item not found"]
5  },
6  "message": "Failed to detach knowledge item"
7}

Detachment Behavior

Immediate Effect

Once detached, the agent immediately stops using the knowledge item:

  1. RAG Retrieval: Agent no longer searches this knowledge item during queries
  2. Context Exclusion: Chunks from this item are excluded from LLM prompts
  3. No Data Deletion: The knowledge item itself is not deleted

Knowledge Item Preservation

The knowledge item remains intact after detachment:

  • Still exists in the team’s knowledge items
  • Can be attached to other agents
  • Can be re-attached to the same agent later
  • No need to re-process

Multiple Agents

If the knowledge item is attached to multiple agents:

  • Only the specified agent is affected
  • Other agents continue using the knowledge item
  • Each agent-knowledge item relationship is independent

Use Cases

Temporary Removal

Temporarily disable knowledge without deleting:

$# Remove outdated FAQ during update
>curl --request DELETE "https://app.resemble.ai/api/v2/agents/support-agent/knowledge_items/old-faq-uuid" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"
>
># Later, re-attach updated FAQ
>curl --request POST "https://app.resemble.ai/api/v2/agents/support-agent/knowledge_items" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  --data '{"knowledge_item_uuid": "new-faq-uuid"}'

Agent Specialization

Remove general knowledge from specialized agents:

$# Billing agent doesn't need technical documentation
>curl --request DELETE "https://app.resemble.ai/api/v2/agents/billing-agent/knowledge_items/tech-docs-uuid" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"

Knowledge Rotation

Swap knowledge items for different use cases:

$# Remove general product info
>curl --request DELETE "https://app.resemble.ai/api/v2/agents/sales-agent/knowledge_items/general-uuid" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"
>
># Add detailed pricing info
>curl --request POST "https://app.resemble.ai/api/v2/agents/sales-agent/knowledge_items" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  --data '{"knowledge_item_uuid": "pricing-uuid"}'

Troubleshooting

Remove problematic knowledge temporarily:

$# Knowledge item causing irrelevant responses
>curl --request DELETE "https://app.resemble.ai/api/v2/agents/agent-uuid/knowledge_items/problematic-uuid" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"
>
># Test agent without the knowledge item
># Fix or replace the knowledge item
># Re-attach when ready

Detach vs Delete

Detach (This Endpoint)

  • Removes knowledge item from specific agent
  • Knowledge item remains in team’s collection
  • Other agents can still use it
  • Can be re-attached later without re-processing
  • Use when: Temporarily disabling or reorganizing knowledge

Delete (Delete Knowledge Item)

  • Permanently removes knowledge item from team
  • Automatically detaches from all agents
  • All chunks and embeddings are deleted
  • Cannot be recovered
  • Use when: Knowledge is no longer needed by any agent

Workflow Example

Complete workflow to swap knowledge items:

$# Step 1: Check current knowledge items
>curl --request GET "https://app.resemble.ai/api/v2/agents/agent-uuid/knowledge_items" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"
>
># Response shows current items
>
># Step 2: Detach old knowledge item
>curl --request DELETE "https://app.resemble.ai/api/v2/agents/agent-uuid/knowledge_items/old-uuid" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"
>
># Response: { "success": true, "message": "Knowledge item detached successfully" }
>
># Step 3: Attach new knowledge item
>curl --request POST "https://app.resemble.ai/api/v2/agents/agent-uuid/knowledge_items" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  --data '{"knowledge_item_uuid": "new-uuid"}'
>
># Response: { "success": true, "message": "Knowledge item attached successfully" }
>
># Step 4: Verify new configuration
>curl --request GET "https://app.resemble.ai/api/v2/agents/agent-uuid/knowledge_items" \
>  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Codes

Error CodeDescription
not_attachedKnowledge item not attached to this agent
not_foundAgent or knowledge item not found

Best Practices

Before Detaching

  1. Check Attachments: Use List Agent’s Knowledge Items to confirm attachment
  2. Consider Impact: Understand how removal affects agent responses
  3. Plan Replacement: Have alternative knowledge ready if needed

After Detaching

  1. Verify Removal: Use List Agent’s Knowledge Items to confirm
  2. Test Agent: Verify agent behavior without the knowledge item
  3. Monitor Responses: Check that agent no longer references removed knowledge

Knowledge Management

  • Detach before deleting if you want to confirm impact
  • Keep detached items for potential future use
  • Document why knowledge items were detached
  • Regular audit of attached vs available knowledge

See Also