Set Ballad up, then put it to work.
These guides cover setting up Ballad, which turns what you ship into marketing in your voice, and wiring it to your repo, your site, your analytics and Claude. Start with your first hour, then read the guide for whichever kind of marketing you want Ballad to run.
Getting started with Ballad
From signing in to your first approved piece: the three questions Ballad asks, the setup walkthroughs waiting in your Inbox, and what happens every morning after that.
Read the guide- 01Sign in and point Ballad at your site
- 02Check the positioning it drafts
- 03Choose what Ballad should do
- 04Work the setup walkthroughs
- 05Approve your first piece
Pick the work you want taken off your desk.
These are the four kinds of marketing Ballad runs, and the four you choose from when you sign up. Each guide covers the setup walkthrough, the settings behind it, and what arrives in your Inbox afterwards.
Content marketing
Articles for your blog, researched and written in your voice, on a schedule you set. Where they publish, what they cover, how often, and how a piece gets better after it lands.
- Where articles go
- What the blog is about
- How often, and how deep
- Review, publish, refresh
Social media
Posts, threads and image posts for LinkedIn, X, Bluesky, Threads and Instagram, drafted for you to approve, posted for you where the network allows it.
- Pick your channels
- Connect your accounts
- Set a pace
- Review, post, reply
Newsletter and lifecycle email
A regular issue to your list, and the automatic emails a new subscriber gets. Ballad sends it through your own Resend account, or writes it for the tool you already use.
- How issues are sent
- Who it goes to
- How often, and the welcome
- Consent, and what never happens
Release notes and changelog
What you shipped, turned into notes people read: from your commits, a GitHub release, an agent, or a sentence you type yourself.
- Name the product
- Where the changelog lives
- How releases reach Ballad
- From notes to a launch week
Every surface, and what it's for.
Ballad is six tabs and a settings area. One page each: what lands there, what you do with it, and where it hands off to the rest, plus the parts that earn a page of their own.
Connect Ballad to your stack.
Rendering articles on your own domain, measuring what they do, and letting Claude work inside the loop. The first two are the setup this site runs on.
The Ballad API
Every endpoint: the read-only content API, the revalidate and capability endpoint your site answers, the release and commit webhooks, and the agent API for everything that writes.
- Which API you want
- Authentication
- The content API
- Webhooks and writes
Set up your Next.js blog
Connect a Next.js App Router site to the content API: index and post routes, block rendering, SEO metadata, and automatic refresh when Ballad publishes.
- The package, in five re-exports
- Mint a content API key
- Or build it yourself
- Revalidate on publish
readdraftproposedecidepublishConnect Claude to Ballad
Add Ballad to Claude as a custom connector: sign in with Ballad, pick scopes on the consent screen, and ask Claude for drafts, plan changes, or a status check. Every draft is still reviewed by you.
- Copy the connector URL
- Add a custom connector in Claude
- Sign in and choose scopes
- Keys for other agents
- What you can ask for
Measure what your content does
Install the beacon: a 1.5 KB first-party script that records landings, referrers and conversions on your own domain, with no cookies and no visitor ids.
- Install the beacon
- Fire a conversion
- Keep your canonical tags
- What Ballad stores
Connect Google Search Console
One Google connection: what you rank for and when an article starts slipping, plus Analytics traffic per page if you use it. Read-only, both of them.
- Verify your property
- Connect
- What Ballad does with it
- Beacon, Analytics, or both
Connect X
Approved posts, threads and image posts publish themselves, and impressions, replies and reposts come back every six hours without you typing them.
- Connect the account to a voice
- What publishes automatically
- What comes back
- Reconnecting
Connect LinkedIn
Publish from your profile instead of pasting, with the link as the first comment, and the 60-day reconnect LinkedIn requires, explained up front.
- Connect the account to a voice
- What publishes automatically
- Numbers
- Reconnecting every 60 days
Connect Slack
Each person's Inbox as direct messages from Ballad, workspace news in a shared channel, and Ask Ballad, with quiet hours so nothing arrives while you're asleep.
- Connect it
- Check it works
- What arrives
- Ask Ballad from Slack
Connect Resend for sending
Send newsletter issues and lifecycle email from your own domain, and let bounces, complaints, unsubscribes, opens and clicks come back into Ballad on their own.
- Verify a sending domain
- Make an API key
- Add it as an email account
- Pick it for each voice
- What comes back
Connect Ballad to Vercel Analytics
Close the measurement loop: enable Web Analytics, emit the signup and demo_request events, and connect it so traffic and conversions feed Signals.
- Turn on Web Analytics
- Emit conversion events
- Keep post URLs matching your collection
- Connect it in Ballad
Two endpoints and a webhook.
Everything is authenticated with a bearer token you mint in Ballad under Settings. Responses are plain JSON with typed content blocks, so any stack can render them.
A collection and a page of its published posts: slug, title, tier, date, excerpt, author, permalink, and hero image.
One post as ordered blocks (prose, hero image, pull quote, CTA, code) plus its SEO title, description, canonical, and JSON-LD.
Ballad calls your site when something publishes, so a cached index or post refreshes within seconds instead of on a timer.
Not an API endpoint, but worth having: the guide ships an RSS route and a sitemap entry for every published post.
Not on Next.js? The endpoints are plain HTTP and JSON. Render them however you like.
Read the full API reference