Retrieval

Synced sources and uploaded documents form a semantic search index that agents access through retrieval-augmented generation (RAG).

Overview

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

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

Text and file uploads are queued as ingestion jobs and become searchable after indexing completes.

Adding content

Click Add content to upload content in either of two ways:

Namespaces

Namespaces 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 verifies that retrieval returns the expected content for representative queries.

version: "1.0"

name: support-agent
type: llm
model: connic/gpt-5.6-terra
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

Synced Sources

Connect Notion, Confluence Cloud, Superhuman Docs (Coda), Zendesk Help Center, or a website from Retrieval → Sources. Each source is scoped to the active environment and writes entries into the selected namespace.

• Notion, Confluence, Superhuman Docs, and Zendesk support 15-minute, hourly, 6-hour, daily, or weekly schedules
• Website sources support 12-hour, daily, or weekly schedules
• Choose whether content absent from the connected source is removed from retrieval or retained
• Use Sync now for an on-demand run and inspect source-run counts and errors from the source details
• Project credit is charged for each item ingested during a source run

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 an 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:

Agents can store summaries of processed documents and delete entries through these tools. 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 supports retrieval uploads, queries, browsing, deletion, and source management. The upload, query, browse, and delete endpoints shown here require retrieval.manage. Source lists and source-run results require retrieval.view; connecting, editing, syncing, and removing sources require retrieval.manage.

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": "Document text goes 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" \
  -F 'metadata={"source": "finance", "title": "Q1 Report"}'

# 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}&namespace=docs.api" \
  -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}&namespace=docs.api" \
  -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"