Skip to main content

​
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). Full schemas: OpenAPI reference → Ideas.

​
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. 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 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, 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, gated by the never-implied ideas:destroy scope. Date-level board planning (schedule_idea) likewise has no REST endpoint today.