Start using the Wren AI Cloud API in minutes – from getting your API key to making your first call.
Welcome to the Wren AI Cloud API! This guide will walk you through how to authenticate and begin using the available endpoints.
1. Get Your API Key
To authenticate your requests, you'll need an API key.
Go to API → API Keys from the top navigation bar and generate your key.
Use this key in the Authorization header as a Bearer token:
Authorization: Bearer YOUR_API_KEY2. Start Using the API
Once you have your API key, you're ready to start using the Wren AI endpoints.
All endpoints are available under the base path: https://cloud.getwren.ai/api/v2
The deprecated Legacy endpoints are served only under
https://cloud.getwren.ai/api/v1.
3. Understand project types
Wren AI Cloud has two kinds of projects, and some endpoints behave differently — or are only available — depending on which one you call. Every API section in this reference is labeled with a Project availability badge (✅ / ⛔ per project type) so you can tell at a glance which projects it applies to.
- Classic projects — the standard GenBI experience. You ask a question in natural language and Wren AI generates SQL, runs it, summarizes the result, and can visualize it. Knowledge is curated as structured Instructions and Question-SQL Pairs. New classic projects render charts as Apache ECharts (
/v2); pre-existing projects continue to return Vega-Lite (/v1, see Legacy). - Agentic projects — projects running in agentic mode, where an AI agent plans and carries out multi-step analyses (with skills, memory, and human-in-the-loop review) and can produce richer artifacts. Knowledge and data modeling are managed as Git-backed files through the Files API instead of the structured Instructions / SQL-Pairs endpoints.
At a glance:
| API section | Classic projects | Agentic projects |
|---|---|---|
| Query & Answering | ✅ | ✅ |
| Agentic mode | ⛔ | ✅ |
| Chart Generation | ✅ | ✅ |
| Projects | ✅ | ✅ |
| Metadata | ✅ | ✅ |
| Knowledge — Instructions & SQL Pairs | ✅ | ⛔ |
| Knowledge — Files | ⛔ | ✅ |
| Legacy (v1) | ✅ | ✅ (deprecated) |
Query & Answering or Agentic mode?They are different products, not two tiers of one.
Query & Answering is text-to-SQL: you ask, Wren writes the SQL, runs it, and summarizes. Fast, predictable, and available on both project types.
Agentic mode runs an agent: it plans, takes multiple steps, produces files and charts you can retrieve later, draws on skills and memory, and can stop to ask you a clarifying question. It needs an agentic project.
4. Explore the API
Use the left-hand menu to browse the available endpoints:
- Query & Answering – Convert natural language questions into SQL queries and summaries, synchronously or streamed over Server-Sent Events (SSE) for real-time feedback as the query is processed. Both project types.
- Agentic mode – Run a Wren agent that plans, queries, writes files and draws charts over a versioned SSE contract, plus the artifacts, memory, skills and uploads that surround a turn. Agentic projects only.
- Chart Generation – Create ECharts charts from query results.
- Metadata Introspection – Access deployed models, schema relationships, and virtual views.
- Projects – Create, read, update, and delete projects (create/list require an organization key).
- Knowledge – The Knowledge feature in Wren AI allows you to store and manage verified information that helps the AI generate more accurate and consistent responses. This feature is particularly useful for domain-specific context and frequently asked questions. Classic projects use Instructions and Question-SQL Pairs; agentic projects use the Git-backed Files API instead.
- Legacy – Deprecated v1 endpoints kept for backward compatibility (synchronous
ask, Vega-Lite charts, and the pre-clarification streaming ask). New integrations should use the v2 endpoints above.
That’s all you need to get started!