Retrieval

Upload documents, build a semantic search index, and give your agents access to your organization's knowledge through retrieval-augmented generation (RAG).

Overview

The retrieval lets you upload documents and make their content searchable by your agents. When an agent uses the retrieval_query tool, it runs a semantic search across your uploaded content and returns the most relevant passages. This is commonly known as retrieval-augmented generation (RAG).

Access the retrieval from the Retrieval tab in your project. The retrieval is scoped to the active environment, so production and staging can have different content.

Uploads are indexed asynchronously. Each new text or file upload is queued first, tracked as an ingestion job, and becomes searchable after indexing completes.

Adding content

Click Add content to upload content. You can add content in two ways:

Namespaces

Namespaces let you organize retrieval entries into a hierarchy using dot-separated paths. For example, policies.hr.leave, policies.legal, and products.pricing.

• Browse namespaces in the tree sidebar on the Retrieval page. Click a namespace to filter entries; child namespaces are included
• Agents can search within a namespace and all its sub-namespaces (e.g. querying policies also searches policies.hr.leave)
• Agents can discover the namespace hierarchy at runtime using the retrieval_list_namespaces tool
• Maximum namespace depth is 10 levels

Querying the Retrieval

There are two ways to query the retrieval:

From the Dashboard

Click the Search button on the Retrieval page to open the query dialog. Enter a natural language query and optionally filter by namespace. Results show the matching passages ranked by relevance score, with links to the source entry. This is useful for testing that your retrieval returns the right content for expected queries.

version: "1.0"

name: support-agent
type: llm
model: gemini/gemini-2.5-pro
description: "Answers customer questions using the retrieval"
system_prompt: |
  You are a customer support agent.
  Use the retrieval_query tool to find relevant information
  before answering questions.
tools:
  - retrieval_query

Managing Entries

The retrieval table shows indexed entries. Recent uploads and ingestion failures are tracked separately in the Ingestion panel.

• View details: Click an entry to see its full content, all chunks with token counts, and metadata. For PDFs, page numbers are included per chunk.
• Filter: Narrow the list by selecting a namespace in the sidebar, searching entry IDs, or filtering by content type
• Delete: Remove entries you no longer need. This removes the entry and all its chunks from the search index.
• Upload status: Use the ingestion panel to monitor queued, processing, retrying, completed, and failed jobs.

Managing Retrieval from Agents

Beyond the dashboard, agents can programmatically add and remove retrieval entries using predefined tools:

This lets agents build and maintain their own indexed content over time. For example, an agent could store summaries of processed documents or delete outdated entries. See the Predefined Tools docs for usage details and the Retrieval Tools docs for full configuration options.

Managing Retrieval via the REST API

The REST API provides full programmatic access to retrieval. Use it to automate ingestion at scale, sync content from external systems like a CMS or documentation platform, or build custom upload pipelines in CI/CD. Authenticate with an API key that has retrieval read and/or write permissions.

All retrieval endpoints require an environment_id query parameter because retrieval is scoped per environment.

curl -X POST "https://api.connic.co/v1/projects/{project_id}/retrieval/text?environment_id={env_id}" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your document text here...",
    "namespace": "docs.api",
    "entry_id": "api-reference-v2"
  }'

curl -X POST "https://api.connic.co/v1/projects/{project_id}/retrieval/file?environment_id={env_id}&namespace=reports.q1" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -F "file=@quarterly-report.pdf"

# List entries filtered by namespace
curl "https://api.connic.co/v1/projects/{project_id}/retrieval/entries?environment_id={env_id}&namespace=docs&limit=50" \
  -H "Authorization: Bearer cnc_your_api_key"

# Get all chunks for a specific entry
curl "https://api.connic.co/v1/projects/{project_id}/retrieval/entries/api-reference-v2?environment_id={env_id}" \
  -H "Authorization: Bearer cnc_your_api_key"

# List namespace hierarchy
curl "https://api.connic.co/v1/projects/{project_id}/retrieval/namespaces?environment_id={env_id}&depth=3" \
  -H "Authorization: Bearer cnc_your_api_key"

# Delete a single entry
curl -X DELETE "https://api.connic.co/v1/projects/{project_id}/retrieval/entries/api-reference-v2?environment_id={env_id}" \
  -H "Authorization: Bearer cnc_your_api_key"

# Delete an entire namespace and everything under it
curl -X DELETE "https://api.connic.co/v1/projects/{project_id}/retrieval/namespaces/reports.q1?environment_id={env_id}" \
  -H "Authorization: Bearer cnc_your_api_key"