AI Integration

The AI integration runs an AI feature and returns content you can preview and then confirm, under /api/ai/*. Every feature follows the same two-step flow: POST /api/ai/suggest produces a validated preview artifact without writing anything, and POST /api/ai/generate persists a confirmed artifact and returns the created resource id(s). GET /api/ai/status reports whether the site has AI configured, whether you are a subscriber, and your remaining daily quota.

All AI endpoints accept either a session cookie or a Bearer sync token (Authorization: Bearer <token>), so the web app, native/mobile clients, and CLI tools all use the same routes. AI features are subscriber only: a free account receives 403 subscription_required from /suggest and /generate.

AI is app-wide and Anthropic-only. Every request runs on the site's own ANTHROPIC_API_KEY, held server-side and never returned by any endpoint. There are no per-user provider keys: access is gated on an active subscription alone. (Per-user keys were removed on 2026-09-05; clients that previously sent one should stop.)

The suggest → generate flow

The two-step design lets a client show a preview and get explicit user confirmation before anything is written:

1. Suggest. POST /api/ai/suggest validates your input, resolves a provider/model, checks quota, calls the model, and validates the model's output into a typed artifact. It returns the artifact plus token usage and quota. Nothing is saved.
2. Confirm and generate. The client shows the artifact to the user. On confirmation, send that same artifact back to POST /api/ai/generate. The server re-validates it (defense in depth) and persists it, returning the created resource id(s).

Both steps count against your daily quota and are recorded in a per-user audit ledger that stores token counts and status only — never prompt or output text.

Endpoint table

Endpoint reference

POST /api/ai/suggest

Auth required: yes (Session or Bearer) Subscriber only: yes Description: Run an AI feature and return a validated preview artifact. Writes nothing.

Request body

{
  "feature": "powered_template | powered_document | message_series | article_series | writing_assist",
  "input": "the user's free-text instruction or draft",
  "context": { "…feature-specific fields…": "see Context below" },
  "model": "model id  (optional override)",
  "maxOutputTokens": 2048
}

Response 200 OK

{
  "ok": true,
  "feature": "writing_assist",
  "artifact": { "kind": "message", "content": "Rewritten draft…" },
  "usage": { "inputTokens": 412, "outputTokens": 96, "model": "claude-sonnet-5" },
  "quota": { "usedToday": 7, "dailyLimit": 50 }
}

The artifact shape depends on the feature; see Artifacts by feature.

Error responses

POST /api/ai/generate

Auth required: yes (Session or Bearer) Subscriber only: yes Description: Persist a confirmed artifact returned by /api/ai/suggest.

Request body

{
  "feature": "powered_template | powered_document | message_series | article_series | writing_assist",
  "artifact": { "kind": "…", "…": "the artifact from /suggest, edited if desired" },
  "provider": "anthropic | openai | gemini  (optional, recorded in the audit ledger)",
  "model": "provider model id  (optional, recorded in the audit ledger)",
  "scheduleImmediately": false,
  "crossPost": { "crossPostToBluesky": true, "crossPostToTwitter": true }
}

Response 201 Created

{
  "ok": true,
  "feature": "powered_document",
  "created": { "documentId": "clx…" },
  "quota": { "usedToday": 8, "dailyLimit": 50 }
}

The created object is one of three shapes, depending on what the artifact persists:

Writes are always scoped to the authenticated user; nothing in the artifact controls ownership. A tags, thread, or message artifact (from writing_assist) is not persistable and returns 422 invalid_input — those are meant to be inserted into the composer client-side, not written as standalone content.

Error responses

GET /api/ai/status

Auth required: yes (Session or Bearer) Subscriber only: no (any authenticated user can read their status) Description: Report the providers the site has configured, the caller's subscriber flag, the per-provider fallback models, and remaining daily quota. Never returns keys.

Response 200 OK

{
  "subscriber": true,
  "providers": ["anthropic"],
  "defaultModels": {
    "anthropic": "claude-sonnet-5",
    "openai": "gpt-4.1-mini",
    "gemini": "gemini-2.0-flash"
  },
  "quota": { "usedToday": 8, "dailyLimit": 50, "remaining": 42 }
}

Error responses

Features

feature selects which AI capability runs and, in turn, the artifact shape you get back:

Powered Document modes

powered_document supports four modes, set in context.mode. Derived modes resolve their source server-side under the owning user (IDOR-guarded), and the Research URL fetch goes through the SSRF-guarded fetcher. You pass a reference, not the source text:

If the required reference is missing or not yours, the mode returns 422 invalid_input. Server-fetched context is truncated to a fixed size before it reaches the model, so very large lists or pages are summarized from a capped excerpt.

Context object

context is optional and id-based. Fields are feature-specific; unknown fields are ignored. Numeric hints are clamped server-side.

Artifacts by feature

An artifact is the single typed envelope for "content an AI produced". /suggest returns one; /generate accepts one back. Every artifact has a kind.

list (from powered_template):

{
  "kind": "list",
  "title": "Conference Talks",
  "description": "Talks I want to submit this year.",
  "dsl": { "name": "Conference Talks", "fields": [ { "…": "DSL schema object" } ] },
  "rows": [ { "field_key": "value" } ]
}

The dsl is a full List Schema DSL object (see List Schema DSL), validated on both suggest and generate. The model is constrained to at most 20 fields, each with a key matching ^[a-z][a-z0-9_-]*$; schemas beyond that fail validation. Starter rows that fail schema validation are dropped rather than failing the whole artifact.

document (from powered_document):

{
  "kind": "document",
  "title": "Getting Started with Widgets",
  "markdown": "# Getting Started…",
  "outline": ["Overview", "Setup", "Next steps"],
  "isPublic": false
}

message_series (from message_series):

{
  "kind": "message_series",
  "listTitle": "Launch thread",
  "items": [
    { "order": 1, "content": "1/ Today we shipped…", "crossPostTargets": ["mastodon"] },
    { "order": 2, "content": "2/ Here's why it matters…" }
  ]
}

On generate, the default is a list whose rows are scheduled posts, spaced a fixed 4 minutes apart (context.spacingMinutes and any model-supplied timestamps are ignored). The row Channels come from the composer's cross-post selection (crossPost); the model's per-item crossPostTargets are used only for sizing hints.

When scheduleImmediately: true, the series skips the list and becomes individual scheduled posts instead — top-level messages the publish-scheduled-messages cron later posts (and cross-posts). The first fires ~30–45 minutes out and each subsequent one 5–10 minutes after the previous. Every post carries the same cross-post config, sanitized from crossPost against your own connected accounts. The response is { scheduledMessageIds, firstScheduledAt, lastScheduledAt }.

doc_series (from article_series):

{
  "kind": "doc_series",
  "folderTitle": "Kubernetes from Scratch",
  "documents": [
    { "order": 1, "title": "Introduction", "outline": ["Why", "What"], "markdown": "# Introduction…" },
    { "order": 2, "title": "Core Concepts", "markdown": "# Core Concepts…" }
  ]
}

On generate, this creates a folder (name de-duplicated) and one document per entry, in order.

writing_assist artifacts — one of three, depending on context.action:

{ "kind": "message", "content": "Rewritten or tightened draft" }

{ "kind": "thread", "parts": ["1/ …", "2/ …"] }

{ "kind": "tags", "tags": ["kubernetes", "devops"] }

These are meant to be inserted into the composer by the client. They are not accepted by /generate.

Provider resolution

Every call resolves to Anthropic, using the site's own ANTHROPIC_API_KEY. There is nothing per-user to resolve: a provider field in the request body is ignored.

The model is the request model if supplied, else the Anthropic fallback from defaultModels (see GET /api/ai/status). If the server has no key set, the call returns 409 no_provider_configured. The key is used only to call Anthropic and is never included in any response.

The OpenAI and Gemini adapters remain in the codebase but are dormant and unreachable.

Input and output limits

Every ceiling below is enforced server-side. maxOutputTokens may request smaller than the feature's ceiling but is clamped down, never up.

Other bounds:

• Composer 10-word gate. message_series and article_series require at least 10 words of input; less returns 422 invalid_input. This matches the composer, where the series generator buttons stay inactive until the draft has enough content.
• Series counts. message_series produces 3–12 items (default 5); article_series produces 2–6 documents (default 4). context.count is clamped into range.
• Content caps. A generated document is capped at 40,000 characters; a single message at 3,000 characters. Server-fetched context (a list dump or a page's text) is truncated to 12,000 characters.
• Daily quota. 50 AI generations per rolling 24 hours per user. At the cap, calls return 429 quota_exceeded. Both phases count: a /suggest and its follow-up /generate are two generations. Failed attempts also count — a call that ends in invalid_ai_output, refused, or provider_error still consumes one generation, so build in retry restraint.
• Rate limit. In addition to the daily quota, /suggest and /generate are rate limited to 15 requests per 60 seconds per user; tripping it returns 429 rate_limited (distinct from quota_exceeded) with a Retry-After header giving the seconds to wait. The limiter is a best-effort, per-server-instance fixed window, so under horizontal scaling the effective ceiling can be somewhat higher — treat 15/60s as the guaranteed floor, not a hard cap.

Error responses

All AI errors share the shape { "error": "human message", "code": "machine_code" }, so clients can switch on code without parsing prose.

A 422 refused code also exists for the case where a provider declines to answer; treat it like invalid_ai_output (retry with different input). Note the two provider_error rows above share one code across HTTP 500 and 502.

Examples

Preview a rewrite of a composer draft:

POST /api/ai/suggest
Authorization: Bearer 3f1c9e...<64 hex chars>...a8
Content-Type: application/json

{
  "feature": "writing_assist",
  "input": "we shipped the new thing today its pretty cool and fast",
  "context": { "action": "rewrite", "targetPlatform": "mastodon" }
}

Preview a document from one of your lists, then confirm it:

POST /api/ai/suggest
Authorization: Bearer <token>
Content-Type: application/json

{
  "feature": "powered_document",
  "input": "Summarize this reading list into a blog-style overview.",
  "context": { "mode": "from_list", "listId": "clx123abc" }
}

POST /api/ai/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "feature": "powered_document",
  "artifact": { "kind": "document", "title": "My Reading Overview", "markdown": "# My Reading Overview…" }
}

Check what you can use before offering AI actions in a client:

GET /api/ai/status
Authorization: Bearer <token>

Related

• Settings (Help Center): how AI features are gated. There are no provider keys to set.
• Lists (API) and List Schema DSL: the shape a powered_template artifact produces.
• Documents (API): what powered_document and article_series write.
• Messages (API): scheduled posts, which a message_series list mirrors.
• Authentication & OAuth: session cookies and Bearer sync tokens accepted by these endpoints.
• API overview: base URL, authentication at a glance, and response conventions.
• API explorer: try endpoints live with the interactive Swagger console.