# Outline API: a free outline in your voice, reviewed before drafting · ScriptGrain > POST /v1/outlines or the create_outline MCP tool writes a markdown outline in a voice profile, free, so the structure can be reviewed before generate_content drafts from it. Canonical: https://scriptgrain.com/us/api/outline # Outline API: plan a piece in your voice before you draft it *By Jack Stovell [X](https://x.com/StovBuilds) · [Instagram](https://www.instagram.com/stovbuilds) · [LinkedIn](https://www.linkedin.com/in/jackstovell/) · published 2026-10-29* The Outline API plans a piece in your voice for free. You send a brief to POST /v1/outlines, get back a markdown outline, and agree the structure before a single credit is spent. Developers call it from the REST API; assistant users reach it through the MCP server. Both are on every plan, Free included. ## At a glance **What it does:** Writes a markdown outline in the voice, free, so you can fix the structure before any credit is spent on a draft. · Endpoint · `POST /v1/outlines` MCP tool · `create_outline` Cost · Free, always: no credit is charged Plans · Every plan, Free included ## How an outline becomes a draft The call returns a markdown outline: H2 sections, each with a one-line description. It's written in the voice, by a small model, and no credit is charged. Ever. So the outline isn't a throwaway. It's stored as a new generation with status outline, and the id that comes back is the thing you carry forward. 1. Call POST /v1/outlines with your brief. You get a generation_id. 2. Read the outline, show it to whoever needs to approve it, adjust the brief if the structure is off. 3. Pass the generation_id to POST /v1/generations (generate_content) to draft from it. The profile, brief, content type and target stored on the outline are reused, so you don't resend them. The same id then tracks the piece through its life: outline, then drafted, then edited after save_edit. One id, three states. If you want the drafting side in full, [content generation](https://scriptgrain.com/us/api/content-generation) covers it. Auth is an sg_live_ key, minted at Settings, then API, sent as Authorization: Bearer. The rate limit is 60 requests a minute per key. ## Templates, companies and long drafts Three options shape what the outline plans. All are optional, and each one changes the result in a different way. - **template_id** starts from a saved brief template. Use list_brief_templates to see what you have, then pass the id you want. - **company_id** grounds the piece in a company profile's facts and audience. Leave it out and the voice's default company is used. - **word_count_target** sets the length you're aiming at. That last one matters more than it looks. Set a target over 5,000 words and the outline plans sections of similar weight, built for a long draft. Without that, a long piece tends to front-load its best material and trail off. Drafts go up to 15,000 words, so the planning stage is where you stop a 12,000-word piece wandering. The voice itself comes from a profile of 45 measured attributes across eight layers, built by a two-pass stylometric extraction from your own human-written samples. ScriptGrain measures writing. It is never trained on it. ## When to use it Reach for the outline first whenever the structure is the risky part. Three cases come up most. 1. **Long pieces.** The longer the draft, the more a weak structure costs you. Agreeing the plan for free is cheap insurance. 2. **Client sign-off on structure.** A client who approves headings and one-line descriptions is a client who won't ask for a rewrite after the draft lands. Send the outline, get the yes, then spend the credit. 3. **An assistant that shows its plan first.** Through the MCP server at https://mcp.scriptgrain.com/mcp, an assistant can propose the outline, wait for your nod, then draft. The [MCP tool reference](https://scriptgrain.com/reference/mcp-tool-reference) lists the tools. Short, throwaway pieces? Skip it and draft directly. For anything where you'd normally ask "what's the plan?", the outline answers that at no cost. And before you even write the brief, the novelty check tells you whether the voice has made that argument already. ## Request and response Called live on 29 October 2026 in ScriptGrain's own brand profile (the outline is cut short here): ## In Claude, ChatGPT or Cursor Over MCP this is the tool `create_outline`. Connect `https://mcp.scriptgrain.com/mcp` once (a custom connector in claude.ai, developer mode in ChatGPT on the web, the MCP settings in Cursor, or `claude mcp add` in Claude Code), then ask in plain words: > Outline a 1,500-word article in my ScriptGrain voice on why our onboarding emails get ignored. Show me the outline before you write anything. Once you approve the outline, the assistant passes its `generation_id` to `generate_content`. ## Get a key API and MCP access is on every plan, Free included. Create a free account (no card), then mint a key at Settings, then API: it starts `sg_live_`, is shown once, and goes in an `Authorization: Bearer` header. Every request, field and error code is in the [OpenAPI spec](https://scriptgrain.com/openapi.yaml). ## Questions ### Does the Outline API cost credits? No. POST /v1/outlines is written by a small model and no credit is charged, ever. You only spend credits when you pass the generation_id to POST /v1/generations and draft from it. API calls draw on the same credits as the app; there is no separate API quota. ### What do I do with the generation_id? Pass it to POST /v1/generations (generate_content) to draft from the outline. The profile, brief, content type and target stored on the outline are used, so you don't resend them. The same id then tracks the piece: outline, then drafted, then edited after save_edit. ### Can I plan a very long piece? Yes. Drafts go up to 15,000 words. Set a target over 5,000 words and the outline plans sections of similar weight for a long draft. You can also pass template_id to start from a saved brief template, or company_id to ground the piece in a company profile. ### Which plans can use it? All of them. The REST API and the MCP server at https://mcp.scriptgrain.com/mcp are on every plan, Free included. Authenticate with an sg_live_ key minted at Settings, then API, sent as Authorization: Bearer. The rate limit is 60 requests a minute per key. Payments never happen through the API. ## Related - [AI writing API and MCP server](https://scriptgrain.com/us/ai-writing-api-and-mcp-server) - [Works with Claude](https://scriptgrain.com/us/works-with/claude) - [Works with ChatGPT](https://scriptgrain.com/us/works-with/chatgpt) - [Works with Cursor and MCP clients](https://scriptgrain.com/us/works-with/cursor) - [MCP tool reference](https://scriptgrain.com/reference/mcp-tool-reference) - [Pricing](https://scriptgrain.com/us/pricing)