Skip to main content
POST
Plan a content brief

Authorizations

Authorization
string
header
required

Send your API key in the Authorization header as Bearer API_KEY. Account API keys work in every workspace you belong to: send X-Notra-Organization-Id with the workspace id or slug to choose one. Workspace endpoints require it when you belong to more than one workspace; GET /v1/me/workspaces works without it. Organization keys only accept their own workspace there.

Path Parameters

projectId
string
required
Minimum string length: 1
Pattern: ^[A-Za-z0-9_-]{1,100}$
Example:

"b1f2c3d4-0000-4000-8000-000000000000"

Body

application/json
topic
string
required

What the article should target. Replaced by the source prompt when sourceKind is gap, prompt or search_console.

Required string length: 3 - 200
autoApprove
boolean
default:false

Start the writer immediately instead of leaving the brief in draft.

contentSubtype
enum<string>
Available options:
guide,
comparison,
listicle,
how-to,
faq,
alternatives
brandVoiceIds
string[]

Only the first entry is used; it overrides the project's brand identity.

Maximum array length: 8
Minimum string length: 1
Pattern: ^[A-Za-z0-9_-]{1,100}$
competitorIds
string[]
Maximum array length: 2000
Minimum string length: 1
Pattern: ^[A-Za-z0-9_-]{1,100}$
sitemapId
string
Minimum string length: 1
Pattern: ^[A-Za-z0-9_-]{1,100}$
sourceKind
enum<string>
Available options:
manual,
gap,
prompt,
search_console,
ai_search
sourceId
string

Gap, prompt or search-console suggestion id. An open brief for the same source is reused instead of planning a new one.

Minimum string length: 1
existingPageUrl
string<uri>

Existing page the article should refresh instead of creating a competing page.

Maximum string length: 2048

Response

Brief planned successfully

briefId
string
required

New brief id, or the id of an open brief reused for the same source.

brief
object
required

The article plan. Notra's AI planner writes the text fields; updateGeoContentBrief can change them.

status
enum<string>
required
Available options:
draft,
approved,
writing,
completed,
failed
runId
string | null
required

Writer run id. Null when no writer run has started for the brief.

postId
string | null
required

Draft post the writer fills in. Null when none is linked.

organization
object
required