Plan a content brief

Researches the topic and writes a brief, then saves it as a draft article. This books AI credits and is billed. Planning happens inside Notra, which owns the model credentials. Set autoApprove to start the writer in the same call. When sourceKind and sourceId point at a gap that already has an open brief, that brief is returned instead of a new one being planned. If planning exceeds four minutes, the API returns 409 while work may still finish in Notra. Do not retry; list the project’s GEO briefs to find the result.

POST

https://api.usenotra.com

projects

{projectId}

geo

briefs

Plan a content brief

curl --request POST \
  --url https://api.usenotra.com/v1/projects/{projectId}/geo/briefs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "topic": "<string>",
  "autoApprove": false,
  "brandVoiceIds": [
    "<string>"
  ],
  "competitorIds": [
    "<string>"
  ],
  "sitemapId": "<string>",
  "sourceId": "<string>",
  "existingPageUrl": "<string>"
}
'

import requests

url = "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs"

payload = {
    "topic": "<string>",
    "autoApprove": False,
    "brandVoiceIds": ["<string>"],
    "competitorIds": ["<string>"],
    "sitemapId": "<string>",
    "sourceId": "<string>",
    "existingPageUrl": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    topic: '<string>',
    autoApprove: false,
    brandVoiceIds: ['<string>'],
    competitorIds: ['<string>'],
    sitemapId: '<string>',
    sourceId: '<string>',
    existingPageUrl: '<string>'
  })
};

fetch('https://api.usenotra.com/v1/projects/{projectId}/geo/briefs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'topic' => '<string>',
    'autoApprove' => false,
    'brandVoiceIds' => [
        '<string>'
    ],
    'competitorIds' => [
        '<string>'
    ],
    'sitemapId' => '<string>',
    'sourceId' => '<string>',
    'existingPageUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs"

	payload := strings.NewReader("{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenotra.com/v1/projects/{projectId}/geo/briefs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenotra.com/v1/projects/{projectId}/geo/briefs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "briefId": "<string>",
  "brief": {
    "targetPrompt": "<string>",
    "intent": "<string>",
    "contentSubtype": "guide",
    "workingTitle": "<string>",
    "audience": "<string>",
    "jobToBeDone": "<string>",
    "sections": [
      {
        "heading": "<string>",
        "goal": "<string>",
        "claims": [
          "<string>"
        ]
      }
    ],
    "questionsToAnswer": [
      "<string>"
    ],
    "internalLinks": [
      {
        "url": "<string>",
        "anchor": "<string>",
        "why": "<string>"
      }
    ],
    "acceptanceChecklist": [
      "<string>"
    ],
    "recommendedAngle": "<string>",
    "competitorsToCounter": [
      "<string>"
    ],
    "sourcesToReference": [
      "<string>"
    ],
    "missingCoverage": [
      "<string>"
    ],
    "baseline": {
      "sourcePromptId": "<string>",
      "mentionedEngines": 123,
      "totalEngines": 123,
      "engines": [
        {
          "engine": "<string>",
          "mentioned": true,
          "position": 123
        }
      ],
      "competitorMentions": [
        {
          "name": "<string>",
          "engines": 123
        }
      ],
      "citedDomains": [
        {
          "domain": "<string>",
          "engines": 123
        }
      ],
      "capturedAt": "<string>"
    }
  },
  "status": "draft",
  "runId": "<string>",
  "postId": "<string>",
  "organization": {
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "logo": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "limit": 2,
  "remaining": 1,
  "reset": 123
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

Authorizations

Authorization

string

header

required

Send your API key in the Authorization header as Bearer API_KEY.

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: 25

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

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

brief

object

required

Show child attributes

status

enum<string>

required

Available options:

draft,

approved,

writing,

completed,

failed

runId

string | null

required

postId

string | null

required

organization

object

required

Show child attributes

Last modified on September 18, 2026

Plan a content brief

curl --request POST \
  --url https://api.usenotra.com/v1/projects/{projectId}/geo/briefs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "topic": "<string>",
  "autoApprove": false,
  "brandVoiceIds": [
    "<string>"
  ],
  "competitorIds": [
    "<string>"
  ],
  "sitemapId": "<string>",
  "sourceId": "<string>",
  "existingPageUrl": "<string>"
}
'

import requests

url = "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs"

payload = {
    "topic": "<string>",
    "autoApprove": False,
    "brandVoiceIds": ["<string>"],
    "competitorIds": ["<string>"],
    "sitemapId": "<string>",
    "sourceId": "<string>",
    "existingPageUrl": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    topic: '<string>',
    autoApprove: false,
    brandVoiceIds: ['<string>'],
    competitorIds: ['<string>'],
    sitemapId: '<string>',
    sourceId: '<string>',
    existingPageUrl: '<string>'
  })
};

fetch('https://api.usenotra.com/v1/projects/{projectId}/geo/briefs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'topic' => '<string>',
    'autoApprove' => false,
    'brandVoiceIds' => [
        '<string>'
    ],
    'competitorIds' => [
        '<string>'
    ],
    'sitemapId' => '<string>',
    'sourceId' => '<string>',
    'existingPageUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenotra.com/v1/projects/{projectId}/geo/briefs"

	payload := strings.NewReader("{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenotra.com/v1/projects/{projectId}/geo/briefs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenotra.com/v1/projects/{projectId}/geo/briefs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"topic\": \"<string>\",\n  \"autoApprove\": false,\n  \"brandVoiceIds\": [\n    \"<string>\"\n  ],\n  \"competitorIds\": [\n    \"<string>\"\n  ],\n  \"sitemapId\": \"<string>\",\n  \"sourceId\": \"<string>\",\n  \"existingPageUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "briefId": "<string>",
  "brief": {
    "targetPrompt": "<string>",
    "intent": "<string>",
    "contentSubtype": "guide",
    "workingTitle": "<string>",
    "audience": "<string>",
    "jobToBeDone": "<string>",
    "sections": [
      {
        "heading": "<string>",
        "goal": "<string>",
        "claims": [
          "<string>"
        ]
      }
    ],
    "questionsToAnswer": [
      "<string>"
    ],
    "internalLinks": [
      {
        "url": "<string>",
        "anchor": "<string>",
        "why": "<string>"
      }
    ],
    "acceptanceChecklist": [
      "<string>"
    ],
    "recommendedAngle": "<string>",
    "competitorsToCounter": [
      "<string>"
    ],
    "sourcesToReference": [
      "<string>"
    ],
    "missingCoverage": [
      "<string>"
    ],
    "baseline": {
      "sourcePromptId": "<string>",
      "mentionedEngines": 123,
      "totalEngines": 123,
      "engines": [
        {
          "engine": "<string>",
          "mentioned": true,
          "position": 123
        }
      ],
      "competitorMentions": [
        {
          "name": "<string>",
          "engines": 123
        }
      ],
      "citedDomains": [
        {
          "domain": "<string>",
          "engines": 123
        }
      ],
      "capturedAt": "<string>"
    }
  },
  "status": "draft",
  "runId": "<string>",
  "postId": "<string>",
  "organization": {
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "logo": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "limit": 2,
  "remaining": 1,
  "reset": 123
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "recovery": "<string>"
}

Getting Started

Guides

Webhooks

Endpoints

Plan a content brief

Authorizations

Path Parameters

Body

Response