Documentation
Everything you need to build and publish data stories.
What is Thistle?
Thistle turns raw data into interactive, scroll-driven visual narratives — the kind you see on sites like The New York Times or The Pudding. Connect a data source, arrange blocks of text, charts, and highlights, and publish a story that stays live as your data updates.
Connect any data
Public datasets, JSON APIs, or CSV uploads. Your story stays connected to the source.
Build visually
Drag blocks into a narrative: rich text, interactive charts, KPI highlights, and dividers.
Publish and share
One click to publish. Your story gets a permanent URL that anyone can read.
How it works
Pick a data source
Choose from the public dataset catalog, paste a JSON API URL, or upload a CSV file.
Build your story
Add blocks — text for narration, charts for visualization, highlights for key figures. Rearrange by dragging. Everything auto-saves.
Publish
Hit publish and your story gets a shareable URL. Stories are statically generated and cached for fast loading, then revalidated hourly.
Connecting Data
Every story starts with data. Thistle supports three ways to bring data in.
Public Datasets
Browse a curated catalog of free, open datasets. Click one and Thistle fetches the data for you.
JSON API URL
Paste any public JSON endpoint. Thistle fetches the data server-side (no CORS issues), shows you a preview, and lets you name the source before proceeding.
https://api.worldbank.org/v2/country/all/indicator/NY.GDP.MKTP.CD?format=json
The response must be valid JSON. Arrays are truncated to 20 items in preview.
CSV Upload
Drag and drop a .csv file (up to 10 MB). Thistle parses headers automatically and shows a table preview. The first 100 rows are loaded for the story editor.
Building Stories
Stories are built from blocks. Each block is a piece of your narrative — text, a chart, a key figure, or a visual break.
Block types
Text
Rich text with headings, bold, italic, lists. Powered by a full-featured editor. Use this for narration, analysis, and context.
Chart
Interactive data visualization. Choose from line, bar, area, or scatter. Configure axes, colors, and titles.
Highlight
A KPI card for calling out key numbers. Shows a value, a label, and an optional delta with direction arrow.
Divider
A visual separator. Use it to break sections of your story apart. No configuration needed.
Working in the editor
Adding blocks: Click the block type buttons in the palette at the bottom of the editor. The new block appears at the end of your story.
Reordering: Drag blocks using the handle on the left side. Drop them where you want.
Removing: Hover over a block and click the delete button that appears.
Auto-save: Changes save automatically as you type. No save button needed — the editor debounces writes so your work is always preserved.
Preview: Click “Preview” in the toolbar to see how your story looks to readers. You can switch between edit and preview at any time.
Charts
Chart blocks create interactive visualizations from your data. Readers can hover to see exact values.
Chart types
| Type | Best for |
|---|---|
| Line | Trends over time. Temperature changes, stock prices, growth curves. |
| Bar | Comparisons between categories. Country populations, revenue by quarter. |
| Area | Volumes and cumulative values. Market cap, traffic patterns. |
| Scatter | Correlations between two variables. Height vs weight, price vs volume. |
Configuring a chart
When you add a chart block, the editor shows configuration fields: chartType, title, xKey (the field for the X axis), dataKey (the field for the Y axis), and color.
Chart data is stored as a JSON array in the block. Each object in the array represents one data point. The keys you specify in xKey and dataKey must match the field names in your data.
Colors use the design system tokens: var(--color-thistle), var(--color-bloom), var(--color-sage), or any valid CSS color.
Publishing
Click Publish
In the editor toolbar, click the Publish button. This generates a permanent URL slug from your story title.
Share your URL
Your story is available at thistle.gg/s/your-story-slug. Copy and share it anywhere — social media, email, reports.
Stories stay live
Published stories are cached for fast loading and revalidated every hour. When you update your story and re-publish, readers will see the latest version automatically.
Social previews
Each published story automatically generates an Open Graph image with your story title and Thistle branding. When you share a link on Twitter, Slack, or Discord, a rich preview card appears.
Wallet & Authentication
Thistle uses Solana wallet authentication. No passwords, no email — just a wallet signature.
How it works
Connect your wallet
Click “Connect wallet” in the app. Supported wallets: Phantom and Solflare.
Sign a message
Your wallet asks you to sign a verification message. This proves you own the wallet address — no tokens are transferred and no transaction fees are charged.
You're in
A session is created and stored as an encrypted cookie. You stay signed in for 7 days. Your stories are linked to your wallet address.
Exploring without a wallet
You can explore Thistle without connecting a wallet. The app shows demo stories you can open, read, and even edit in sandbox mode. Your edits live in your browser only.
When you connect a wallet, your sandbox edits can be saved as real stories. The transition is seamless — the app stays the same, only ownership changes.
API Reference
Thistle's API is built into the Next.js application. All endpoints live under /api. Authentication uses session cookies set during the wallet sign-in flow.
Authentication
| Method | Path | Description |
|---|---|---|
| GET | /api/auth/nonce | Generate a random nonce for wallet signing |
| POST | /api/auth/verify | Verify wallet signature, create or find user, start session |
| GET | /api/auth/me | Get current authenticated user |
| POST | /api/auth/logout | End session |
Stories
| Method | Path | Description |
|---|---|---|
| GET | /api/stories | List all stories for the authenticated user |
| POST | /api/stories | Create a new story |
| GET | /api/stories/[id] | Fetch a single story with linked data sources |
| PUT | /api/stories/[id] | Update title and/or blocks (auto-save target) |
| DELETE | /api/stories/[id] | Delete a story permanently |
| POST | /api/stories/[id]/publish | Publish a story — generates slug and public URL |
Data Sources
| Method | Path | Description |
|---|---|---|
| GET | /api/data-sources | List data sources for the authenticated user |
| POST | /api/data-sources | Create a data source (type: API, CSV, or PUBLIC) |
| POST | /api/data-sources/preview | Preview a JSON API endpoint (server-side fetch) |
| GET | /api/public-datasets | List available public datasets |
FAQ
Is Thistle free?
Yes. Thistle is free to use. Connect a wallet, build stories, and publish them at no cost.
Do I need a Solana wallet?
Only if you want to save your work. You can explore demo stories and use the editor in sandbox mode without a wallet. To publish and keep your stories, connect Phantom or Solflare.
What data formats are supported?
JSON APIs and CSV files. For APIs, Thistle fetches the endpoint server-side and parses the JSON response. For CSVs, the file is parsed in your browser with automatic header detection.
Can I use private or authenticated APIs?
Not yet. Thistle currently only supports public JSON endpoints that don't require authentication headers. Authenticated data source support is on the roadmap.
How do published stories stay up to date?
Published stories use Incremental Static Regeneration (ISR). The page is cached for fast loading and revalidated every hour. When you update your story content and re-publish, readers see the latest version on their next visit.
Can I embed a story on my website?
Stories are standard web pages with permanent URLs. You can link to them or embed them in an iframe. A dedicated embed mode with customizable dimensions is planned.
What happens to my data?
For API sources, Thistle fetches data on your behalf and stores a cached copy. For CSV uploads, data is processed in your browser. Story content (blocks, titles, chart data) is stored in a PostgreSQL database linked to your wallet address.
Is there a size limit?
CSV files up to 10 MB. API responses are previewed at 20 items. There's no hard limit on the number of blocks in a story, but very long stories may load slower.