AI and prompts

The choice to make first

The prompt routes return exactly what we would have sent to the model, with your real posts already interpolated. If the caller is itself an AI agent, it should run that prompt and skip the paid route entirely.

Grounding: the context field

Every route on this page takes an optional context string, up to 4,000 characters. Send it whenever you can.

Without it, the prompt contains a topic string and the account's own post history, and nothing else. Ask for posts about something neither one describes and the model does not stop — it invents the missing specifics and writes them as fact. This is not hypothetical: an account whose history was about an unrelated side project, asked for posts about a launch, produced "Just shipped the first version! Time to see how the App Store review goes" for a product with no app and no review.

context is where the real facts go, and the prompt tells the model to take every specific from there or from the posts, and to invent nothing else:

{"topic": "the launch",
 "context": "Shipped a public REST API (22 routes) and an MCP server on npm on 21 Aug. No mobile app."}

Longer input is clamped rather than rejected, and the response says so in warnings with a parameter_clamped entry. Nothing here is stored — context is an input, not part of the account's history.

GET /ai/prompts/suggestions/

Optional ?topic=shipping in public to steer it, ?count= for how many ideas (1–20, default 5), and ?context= for ground truth.

{"status": "success", "data": {
  "handle": "alice.bsky.social",
  "post_count": 128,
  "system": "...",
  "prompt": "...",
  "combined": "..."
}}

Use system and prompt separately, or combined if you have one input box. The prompt asks for a single JSON object containing post_suggestions (a list of strings) plus seven analysis keys.

POST /ai/prompts/suggestions/

The same route and the same response, with {"topic", "count", "context"} in the body instead of the query string.

Prefer it whenever you are sending context. Ground truth tends to run to paragraphs, and a query string is the wrong place for that — it lands in access logs and proxy caches. It is the same reason the rewrite prompt has always been POST-only.

POST /ai/prompts/rewrite/

{"text": "my rambling draft", "instructions": "punchier, under 300 characters",
 "context": "optional ground truth"}

Returns the same system / prompt / combined trio.

POST /ai/suggestions/

Spends one call on your own key. Optional body {"topic": "...", "count": 10, "context": "..."}.

{"status": "success", "data": {
  "handle": "alice.bsky.social",
  "posts_analyzed": 128,
  "suggestions": ["...", "..."],
  "insights": {"tone_style": {"...": "..."}}
}}

With no post history it returns an empty list and a message telling you to sync first, rather than an error.

GET /ai/suggestions/ and DELETE /ai/suggestions/{id}/

Listing stored suggestions is free and works with a read key. Deleting needs write scope, and only ever touches your own account's suggestions.

POST /ai/rewrite/

{"text": "my rambling draft", "instructions": "punchier"}

Returns {"text": "...", "original": "..."}.

This is POST, not GET, on purpose. The internal endpoint the web app uses puts draft text in the query string, which means post content lands in access logs. The public API does not repeat that.

When there is no AI key

Both paid routes return 403 no_ai_key with a prompt_url pointing at the free equivalent, rather than dead-ending. Any agent worth using should follow it.