> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ideas

# Ideas

The idea board is where content ideas live before they become posts:
each idea is a creative brief (title, angle, hook, pillar, supporting
evidence) carrying a workflow status `inbox → in_production → review →
done`. The REST surface covers reads and the reversible writes; the
scopes are `ideas:read` / `ideas:write` — grantable to API keys and
OAuth tokens alike (see [auth.md §1.2](./auth.md#12-scopes)).

Full schemas: **OpenAPI reference → Ideas**.

| Method | Path                 | Scope         | Notes                                                                                          |
| ------ | -------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| GET    | `/v1/ideas`          | `ideas:read`  | Paginated compact list, newest first; `status` filter.                                         |
| GET    | `/v1/ideas/{ideaId}` | `ideas:read`  | One idea in full: brief, media, capture evidence, AI readiness, attached sources, linked post. |
| POST   | `/v1/ideas`          | `ideas:write` | Create at the top of its column. Idempotent.                                                   |
| PATCH  | `/v1/ideas/{ideaId}` | `ideas:write` | Edit the brief field set; `null` clears a field.                                               |

***

## Semantics worth knowing

* **Statuses are derived.** `review` and `done` are computed from the
  linked post's workflow state — you can only *write* `inbox` and
  `in_production`. A `status` filter on the list endpoint filters on the
  derived value, so a page may return fewer than `limit` items.
* **Status is not the dashboard column.** The board's columns are
  customised per workspace and are not exposed on this API; they carry
  no status and nothing moves a card between them but a person. An idea
  created here lands in the workspace's first column whatever its
  `status`, and a status change never moves it.
* **Ordering is board-UI ordering.** Creates land at the top of the
  column; ordering is never a caller input.
* **Both reads clip the body, and neither flags the clip.** A list row
  carries the body as plain text in `excerpt`, cut at 500 characters;
  the single read carries the same body in `content`, cut at 1500 — the
  longest form this API serves, and not necessarily the whole stored
  body, which may be written up to the column's 65,535 bytes. A cut is
  marked with an ellipsis and nothing else: ideas carry no
  `contentTruncated` sibling, so they are the exception to
  [Conventions § Large text fields](./conventions.md#large-text-fields-in-a-list).
  The single read never carries `excerpt`, and the list row never
  carries `content`.
* **`funnelStage` is derived and read-only.** Both reads carry the lane
  the idea aims at — `REACH` (top of funnel), `TRUST` (middle) or
  `CONVERT` (bottom), or `null` when unrated — resolved from the card's
  `postType` (the `pillar` as fallback). Neither write accepts it: set the
  format and the lane follows.
* **Creating an idea creates nothing else.** No post, no calendar
  entry. Planning an idea onto a date, generating a post from it, and
  scheduling to LinkedIn are separate steps.
* **Turning an idea into a post is a generation call.** Pass the card's
  id to [`POST /v1/posts/generations`](./posts.md#post-v1postsgenerations)
  as `source: { "type": "idea", "ideaId": "idea_…" }` — the server
  renders the whole brief, the card's `pillar` fills the content type
  unless you send one, and the generated post is linked back to the
  idea, which is what moves its status to `in_production` (when no post
  was linked yet). It does not move the card between board columns.
* **The detail read carries the idea's `media`.** `mode: "asset"` is
  concrete media — attached images (cover first) or a generated
  carousel's cover, with public `img_…` library ids; `mode:
  "reference"` is a visual style direction only (the media is created
  per post later), carrying the style's name and prompt. `null` means
  no media decision yet — the `assetFormat` brief field is just a
  label and implies no asset. The URL fields
  (`media.images[].imageUrl`, `media.styleImageUrl`) are display links
  to the image bytes and require `media:read` on top of `ideas:read` —
  without it they come back `null` while the ids, mode, style name and
  count stay intact, so images with a null `imageUrl` mean the link is
  withheld, not that the idea has no media. Editing media is MCP-only today:
  [`attach_media_to_idea`](./mcp-tools.md#2-write-tools), a full-state
  write over library images (scope `ideas:write` + `media:read`);
  the brief-field `PATCH` deliberately takes no media.
* **No REST delete.** Deleting an idea cascades across its child
  records (evidence, input requests, note mirrors), so on this API the
  destroy verb is MCP-only and two-phase:
  [`delete_idea`](./mcp-tools.md#2-write-tools), gated by the
  never-implied `ideas:destroy` scope. Date-level board planning
  (`schedule_idea`) likewise has no REST endpoint today.

```bash theme={null}
curl -i https://api.scripe.io/v1/ideas \
  -X POST \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-10" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "projectId": "proj_01J9ZA…",
    "title": "What building our pricing page taught me about honesty",
    "hook": "We rewrote our pricing page 4 times. Only one version converted.",
    "status": "inbox"
  }'
```