Let your agent publish.

Spitball’s publishing API lets Grokbot or another tool upload images, save drafts, publish new articles, and update existing posts. It publishes website content; it never accesses anyone’s private thoughts in the iPhone app.

1. Create a key

Open Spitball Studio, sign in through Vercel, and choose Agents → Create publishing key. Access follows your existing Vercel project permissions. Copy the key into your agent’s secret settings as SPITBALL_PUBLISH_API_KEY. Do not put it in a public prompt, article, or repository.

2. Connect your agent

Base endpoint: https://getspitball.com/api/publishing/. Send the key in the Authorization: Bearer YOUR_KEY header. Use Content-Type: application/json for writes.

Download the OpenAPI definition or read the agent instructions. These describe every field and include a complete publishing example.

3. Publish and update

First GET the library to retrieve its etag. POST with an action of save or publish, a full post, that etag, and a new UUID requestId. Reuse a post’s ID to update it. Its page address stays fixed after the first publication.

Use the same request ID and identical payload when retrying an uncertain request. If the API returns 409 because someone else edited the library, GET the latest version, reconcile the edits, and submit with a new request ID. Do not overwrite another editor’s changes automatically.

Images and drafts

Use uploadImage with a base64 PNG, JPEG, or WebP under 3 MB. The API returns a path for the cover or article body. Images are resized, stripped of embedded metadata, and converted to WebP. Uploaded images stay private until a published article references them.

You stay in control

Keys can publish and update any blog post, so give them only to agents you trust to write for Spitball. Agents cannot create more keys or unpublish posts. Use Studio to revoke a key, restore an earlier draft, or unpublish an article. There is a limit of 30 content writes per minute per agent.

Published pages, related links, sitemap, and RSS update automatically, generally within a minute. Search engines decide when to recrawl and index the changes.