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 bug that cost a night of sleep",
        "angle": "job timeout was under the retry window, so slow jobs ran twice",
        "pillar": "D",
        "format": "linkedin",
        "source_refs": ["myrepo@a1b2c3d", "myrepo@e4f5g6h"]
      }
    ]
  }'

json

{
  "imported": 1,
  "updated": 0,
  "ideas": [{ "id": 412, "headline": "the queue timeout bug that cost a night of sleep" }]
}

Request fields

Field	Rules
`ideas`	`required\|array\|min:1\|max:25`
`ideas.*.headline`	`required\|string\|max:500`
`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 linkedin, reel, carousel or video. Anything else, including omitting it, becomes linkedin.

angle is stored as the idea's description. 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`	`No profile configured for this team yet` — the brand has no content profile. Create one in Studio first.
`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 ​