Prompts and Competitors

Prompts are the questions Notra asks AI engines on your behalf. Competitors are the brands it looks for in the answers next to yours. Both live under the Visibility group of the GEO sidebar and are scoped to the active project.

Tracked prompts

The Prompts page lists every prompt that goes into a scan. There are two sources:

Custom prompts you add by hand, import, or accept from a suggestion. They are stored per project with an enabled flag.
Auto prompts derived from the project’s brand context. Notra reads the brand identity’s company description and audience, extracts a product category and an audience phrase, and generates a small set of category questions that never name your brand. Auto prompts are regenerated from the brand context on every read; they are always listed as enabled and have no createdAt.

Each prompt is written the way a person types into ChatGPT: lowercase, one intent, no trailing question mark, usually with a concrete detail about the person’s situation (role, team size, budget, stack) and never in the brand’s own category jargon. A custom prompt must be between 8 and 300 characters. Suggested prompts that contain your company name or an alias are dropped during onboarding, because a branded question tells you nothing about unaided recall.

Adding and pausing prompts

Press Add Prompt (shortcut P). The dialog has a Question field and, for suggestions, a Website field. The prompts table shows a Presence badge per prompt (Search only when only the grounded engines named you, Invisible when no engine did), the Engines that mentioned you, and the Best position. Custom prompts can be paused without deleting them; a paused prompt is skipped by the next scan and keeps its history.

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/prompts \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "what tools should i use for automating changelogs" }'

curl -X PATCH https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/prompts/$PROMPT_ID \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

curl -X DELETE https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/prompts/$PROMPT_ID \
  -H "Authorization: Bearer $NOTRA_API_KEY"

GET /v1/projects/{projectId}/geo/prompts returns both sources in one list. Each item has id, prompt, enabled, source (custom or auto), and createdAt.

Bulk import

Import CSV on the Prompts page accepts a file with a prompt column and an optional enabled column. The dialog summarises Ready to import, Duplicates skipped, and Rows with problems before you confirm. The API endpoint accepts either structured rows or raw csv text. Prompts that already exist are skipped, not duplicated.

array

1 to 500 objects with prompt (8 to 300 characters, required) and enabled (boolean, optional).

string

Raw CSV text, up to 1 MiB, with a prompt column and an optional enabled column. Used when rows is omitted.

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/prompts/import \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "prompt": "what tools should i use for automating changelogs" },
      { "prompt": "best way to turn github activity into a blog post", "enabled": false }
    ]
  }'

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/prompts/import \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "csv": "prompt,enabled\nwhat tools should i use for automating changelogs,true" }'

{
  "imported": 2,
  "updated": 0,
  "skipped": 0,
  "issues": [],
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

issues lists rejected CSV lines as { line, message } and is always empty for rows. Import allows 10 requests per 10 minutes per organization.

Search Console suggestions

The Prompts page also hosts the Google Search Console card: “We read the queries your site ranks for and suggest the AI prompts people ask. Suggestions refresh weekly.” Press Connect Search Console, choose a Property, and Notra syncs the last 28 days of queries every Monday (Sync now runs it immediately). Suggestions appear in a table with Search queries, Impressions, Clicks, and Best position; press Track to turn one into a custom prompt. Suggestions you have not accepted also feed the search gaps on Content Gaps.

Conversations

A conversation (a prompt sequence in the API) is a multi-turn exchange of up to five turns. It captures how an engine answers once a buyer has narrowed the question, for example “what tools automate changelogs” followed by “which of those integrate with linear”. A project can hold up to ten conversations. The Conversations card on the Prompts page lists each sequence with its Turns count and whether it is Included in scans or paused. New conversation opens a dialog with Name and Turns fields. Conversations are replayed against the grounded engines during every English scan; the per-turn results appear as a replay thread.

Running a conversation now

The play button on a row runs that conversation immediately. The API equivalent is synchronous:

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/sequences \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Changelog tool research",
    "steps": [
      "what tools automate changelogs from github",
      "which of those integrate with linear"
    ]
  }'

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/sequences/$SEQUENCE_ID/run \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  --max-time 330

{
  "checks": 8,
  "mentions": 3,
  "engines": ["openai/gpt-5.4-grounded", "anthropic/claude-sonnet-4.6-grounded"],
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

integer

Recorded answers across every engine that responded.

integer

How many of those answers mentioned the tracked brand.

string[]

Engines the conversation was played against.

The run is not queued. The request stays open for the whole run, which can take several minutes. Use a client timeout of at least five minutes. After four minutes the API stops waiting and answers 409 while the run finishes on its own; do not retry, read the result from the project’s prompt results instead. This endpoint allows 10 requests per 10 minutes per organization.

PATCH /geo/sequences/{sequenceId} accepts name, steps (1 to 5), and enabled. DELETE removes the sequence.

Competitors

The Competitors page answers “Who AI engines recommend instead of you”. Notra matches competitor names case-insensitively in every answer, so the list you keep here decides what share of voice and content gaps can see. A project can track up to 25 competitors. Each competitor has:

Name: the primary string matched in answers.
Website: a bare domain such as example.com, used for the logo and for suggestions.
Type: Direct (“Sells what you sell”) or Indirect (“Solves the same problem differently”).
Synonyms: up to eight alternative spellings or product names that count as the same brand.
Chart color: the color used in share of voice charts.

The table has Domain, Type, and Synonyms columns with a name filter and an All types / Direct / Indirect filter. Add Competitor (shortcut C) opens the edit form. Below the table, the Share of voice card compares mention counts for the selected range.

Create, rename, and delete

The API uses a single PUT for create and update. It matches on name, case-insensitively, and returns the full competitor list.

curl -X PUT https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/competitors \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beamer",
    "domain": "beamer.com",
    "kind": "direct",
    "synonyms": ["getbeamer"],
    "color": "#7c3aed"
  }'

To rename, send the new name and the old one as previousName:

curl -X PUT https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/competitors \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Beamer Changelog", "previousName": "Beamer", "domain": "beamer.com" }'

string

required

1 to 128 characters.

string

Set to rename an existing competitor.

string | null

required

Website domain, up to 128 characters, or null.

string[]

Up to 8 entries.

'direct' | 'indirect'

Defaults to direct when omitted on create.

string | null

Chart color, up to 128 characters.

DELETE /v1/projects/{projectId}/geo/competitors/{name} stops tracking a competitor. The name is matched case-insensitively.

Suggestions for a domain

Notra can discover likely competitors for a website. Results are cached per organization and domain.

curl "https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/competitors/suggestions?domain=usenotra.com" \
  -H "Authorization: Bearer $NOTRA_API_KEY"

{
  "domain": "usenotra.com",
  "field": "content automation",
  "competitors": [
    { "name": "Beamer", "domain": "beamer.com", "description": "Changelog and product update tool", "confidence": "high" }
  ],
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

confidence is high, medium, or null. This endpoint allows 10 requests per 10 minutes per organization.

Bulk import

Import CSV on the Competitors page and the API import endpoint share the same rules: a name column is required, domain, kind, and synonyms are optional, and existing competitors are updated in place rather than duplicated.

array

1 to 25 objects with name (required), domain, kind, and synonyms (up to 8).

string

Raw CSV text, up to 1 MiB, with a name column and optional domain, kind, synonyms columns. Used when rows is omitted.

curl -X POST https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/competitors/import \
  -H "Authorization: Bearer $NOTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Beamer", "domain": "beamer.com", "kind": "direct" },
      { "name": "Headway", "domain": "headwayapp.co", "kind": "direct", "synonyms": ["headway app"] }
    ]
  }'

The response carries imported, updated, skipped, issues[], and the full competitors[] list. Import allows 10 requests per 10 minutes per organization.

Competitor detail

Clicking a competitor opens its detail view, as a modal from the Competitors page or as a full page at /geo/competitors/{name}. It shows a Mentions chart over the last 30 days by default and a table of the prompts that produced those mentions with Engine, Position (the numeric position, Mentioned, or Absent), and Last seen columns. Edit competitor opens the same form as the table. The API equivalent is GET /v1/projects/{projectId}/geo/visibility/competitors/{brand}, where brand is the name as reported by competitor-share. Without a window it falls back to the 30-day competitor-detail default rather than the project default.

Bulk import GEO prompts

Full request and response schema.

Create or update a competitor

Full request and response schema.

Get Started

Core Concepts

GEO

Integrations

Developer Tools

Automation

Content Types

Organization

Tracked prompts

Adding and pausing prompts

Bulk import

Search Console suggestions

Conversations

Running a conversation now

Competitors

Create, rename, and delete

Suggestions for a domain

Bulk import

Competitor detail

Bulk import GEO prompts

Create or update a competitor

​Tracked prompts

​Adding and pausing prompts

​Bulk import

​Search Console suggestions

​Conversations

​Running a conversation now

​Competitors

​Create, rename, and delete

​Suggestions for a domain

​Bulk import

​Competitor detail

Bulk import GEO prompts

Create or update a competitor

Tracked prompts

Adding and pausing prompts

Bulk import

Search Console suggestions

Conversations

Running a conversation now

Competitors

Create, rename, and delete

Suggestions for a domain

Bulk import

Competitor detail