Ideas

Two endpoints, and they are the reason the API exists for most integrators: they let something running on your own machine turn your work into content ideas without Postlyra ever reading your files.

Ideas land in the review queue with status new. Promoting one into a draft, and approving that draft, both happen in Studio.

`GET /ideas/mining-context`

Everything a client needs before it drafts anything: your brand's voice, its pillars, its persona, and the source refs already attached to existing ideas.

bash

curl https://api.postlyra.com/ideas/mining-context \
  -H "Authorization: Bearer $POSTLYRA_TOKEN" \
  -H "X-Postlyra-Brand: $BRAND_ID"

json

{
  "refs": ["myrepo@a1b2c3d", "vault:content-inbox.md@3f9a21bc"],
  "known": "Recently published or queued: ...",
  "voice": "Simple, direct, conversational English ...",
  "pillars": "A: build-in-public. B: technical takes ...",
  "persona": "Solo SaaS founder ..."
}

Field	What it is
`refs`	Every source ref already attached to an idea, within a 90 day window. Drop matching material before you spend tokens on it.
`known`	A summary of recent ideas and published hooks, so a client avoids repeating a theme.
`voice`	The brand's voice guide.
`pillars`	The brand's content pillars.
`persona`	Who the brand is and who it talks to.

Call this first. Filtering on refs before the AI call is the primary dedup mechanism: it works across machines and it saves tokens.

`POST /ideas/import`

Push finished ideas. Up to 25 per call.

bash

curl -X POST https://api.postlyra.com/ideas/import \
  -H "Authorization: Bearer $POSTLYRA_TOKEN" \
  -H "X-Postlyra-Brand: $BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ideas": [
      {
        "headline": "The queue timeout that ran jobs twice",
        "angle": "My job timeout was shorter than the retry window, so every slow job ran twice.\n\nNo error, no failed run. Just numbers that were quietly double what they should be, for a week.\n\nIf a job can be retried, the timeout has to be longer than the window that retries it. I now check that pair in code review before anything else.",
        "pillar": "D",
        "format": "text",
        "source_refs": ["myrepo@a1b2c3d", "myrepo@e4f5g6h"]
      }
    ]
  }'

json

{
  "imported": 1,
  "updated": 0,
  "ideas": [{ "id": 412, "headline": "The queue timeout that ran jobs twice" }]
}

Request fields

Field	Rules
`ideas`	`required\|array\|min:1\|max:25`
`ideas.*.headline`	`required\|string\|max:255`
`ideas.*.angle`	`nullable\|string`
`ideas.*.pillar`	`nullable\|string`
`ideas.*.format`	`nullable\|string`
`ideas.*.recording`	`nullable\|string`
`ideas.*.source_refs`	`required\|array\|min:1`
`ideas..source_refs.`	`string\|max:255`

format accepts text, reel, carousel or video (linkedin and post are legacy aliases for text). Anything else, including omitting it, becomes text.

headline is a short working title for the idea list, not the post text. angle carries the finished post text and is stored as the idea's body. recording is stored as reel instructions and is where you put concrete screen-recording notes for a video idea.

Source refs and idempotency

source_refs is required, and it is what makes re-running safe.

Idea text comes out of an AI, so the same input through two runs produces different headlines. Text can never answer "have I already imported this". The ref can. A ref is a stable identity string for the material an idea came from:

Material	Ref format	Example
A git commit	`<repo-label>@<short-sha>`	`myrepo@a1b2c3d`
A note file	`vault:<filename>`	`vault:2026-08-14-queue-bug.md`
One bullet in a running list	`vault:<filename>@<hash>`	`vault:content-inbox.md@3f9a21bc`

You can invent your own scheme. The only requirements are that the same material always produces the same string, and that different material never collides.

On import, Postlyra computes an idempotency key from the sorted refs plus the headline. Pushing the same headline with the same refs updates the existing idea rather than creating a second one, so a retry after a failed push is safe.

Errors

Status	Cause
`422`	Validation failed. More than 25 ideas, a missing headline, or an empty `source_refs`.
`403`	The `X-Postlyra-Brand` value is not a brand you belong to.

The same thing over MCP

get_mining_context and push_ideas are the same operations through the MCP server, backed by the same code. Use whichever fits: REST if you are writing a script, MCP if an agent is already reasoning about the material.

Ideas ​

GET /ideas/mining-context ​

POST /ideas/import ​

Request fields ​

Source refs and idempotency ​

Errors ​

The same thing over MCP ​