Knowledge

Store verified domain knowledge — instructions, question-SQL pairs, and files — so Wren AI generates accurate, consistent answers.

Project availability: varies by knowledge type.
• Instructions — ✅ Classic projects • ⛔ Agentic projects
• Question-SQL Pairs — ✅ Classic projects • ⛔ Agentic projects
• Files — ⛔ Classic projects • ✅ Agentic projects only

Classic projects manage knowledge as structured Instructions and Question-SQL Pairs. Agentic projects manage knowledge and modeling as Git-backed Files instead; calling the Instructions or SQL-Pairs endpoints against an agentic project returns AGENT_MODE_V1_DEPRECATED, and calling the Files endpoints against a non-agentic project returns PROJECT_NOT_AGENTIC.

The Knowledge feature in Wren AI lets you store and manage verified information that helps the AI generate more accurate and consistent responses. It's especially useful for capturing domain-specific context, business rules, and frequently asked questions so answers stay aligned with how your organization actually works.

Knowledge is made up of three building blocks, each with its own API:

• Instructions — natural-language guidelines that shape how Wren AI writes SQL and responds (business rules, data-model conventions, query patterns, tone).
• Question-SQL Pairs — curated mappings from a natural-language question to a known-good SQL query, reused when users ask similar questions.
• Files — direct, Git-backed read/write access to the project's knowledge/ and mdl/ files. Available in agentic projects only.

Endpoints Overview

Instructions — /v2/projects/{projectId}/knowledge/instructions

• GET /v2/projects/{projectId}/knowledge/instructions: List all instructions.
• POST /v2/projects/{projectId}/knowledge/instructions: Create a global instruction (isGlobal: true) or a question-matching instruction (provide questions).
• PUT /v2/projects/{projectId}/knowledge/instructions/{id}: Update an instruction.
• DELETE /v2/projects/{projectId}/knowledge/instructions/{id}: Delete an instruction.

Question-SQL Pairs — /v2/projects/{projectId}/knowledge/sql_pairs

• GET /v2/projects/{projectId}/knowledge/sql_pairs: List all SQL pairs.
• POST /v2/projects/{projectId}/knowledge/sql_pairs: Create a SQL pair. The sql is dry-run validated against the latest deployment before it's saved.
• PUT /v2/projects/{projectId}/knowledge/sql_pairs/{id}: Update a SQL pair.
• DELETE /v2/projects/{projectId}/knowledge/sql_pairs/{id}: Delete a SQL pair.

Files (agentic projects only) — /v2/projects/{projectId}/files

• GET /v2/projects/{projectId}/files: List files in the project's shared-data repository (optionally under a prefix).
• GET /v2/projects/{projectId}/files/{path}: Read a single file.
• PUT /v2/projects/{projectId}/files/{path}: Create or update a file under knowledge/ or mdl/.
• DELETE /v2/projects/{projectId}/files/{path}: Delete a file under knowledge/ or mdl/.
• POST /v2/projects/{projectId}/files/batch: Apply multiple upserts/deletes as a single atomic commit.

When to Use Which API

Pick the knowledge type that matches what you're trying to teach Wren AI:

I want to…	Use This
Steer how the AI answers with reusable guidance (e.g. "revenue means net revenue", "exclude test accounts")	Instructions
Pin a specific, reusable SQL answer to a question so similar questions return trusted SQL	Question-SQL Pairs
Programmatically manage the raw knowledge/ and mdl/ files in an agentic project (bulk import, sync, atomic commits)	Files

🔹 Instructions — shape behavior, not a specific answer

Availability: ✅ Classic projects • ⛔ Agentic projects (use Files instead).

Best when you want to influence every relevant answer rather than pin one exact result:

• Global instructions (isGlobal: true) apply to every question — use for org-wide rules and conventions.
• Question-matching instructions (provide questions) apply only when the user's question matches the given topics — use for context that's relevant to some questions but not others.

Instructions guide reasoning. If you need Wren AI to always return one specific query for a known question, use a Question-SQL Pair instead.

🔹 Question-SQL Pairs — reuse trusted SQL for known questions

Availability: ✅ Classic projects • ⛔ Agentic projects (use Files instead).

Best for frequently asked questions and reporting queries where you already know the exact SQL you want returned. When users ask similar questions, Wren AI reuses the paired SQL for more accurate, consistent results. The sql is dry-run validated against the latest deployment before it's saved, so broken queries are rejected up front.

🔹 Files — Git-backed knowledge & modeling for agentic projects

Availability: ⛔ Classic projects • ✅ Agentic projects only.

Agentic projects only. These endpoints are backed by the project's shared-data Git repository (branch main). Requests against non-agentic projects fail with PROJECT_NOT_AGENTIC.

Best when you need direct, version-controlled access to the underlying files rather than structured records:

• Reads are allowed for any path in the repo; writes are restricted to the knowledge/ and mdl/ prefixes.
• Use PUT /files/{path} for a single file, or POST /files/batch to apply many upserts/deletes as one atomic commit — ideal for bulk import or syncing knowledge and MDL from your own source of truth.

🔗

Learn more

• Knowledge overview for classic projects
• Knowledge overview for agentic projects