> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenotra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompts and Competitors
> Manage the questions Notra asks AI engines, multi-turn conversations, and the competitors it watches for in answers
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.
```bash Create theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" }'
```
```bash Pause theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 }'
```
```bash Delete theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
1 to 500 objects with `prompt` (8 to 300 characters, required) and `enabled` (boolean, optional).
Raw CSV text, up to 1 MiB, with a `prompt` column and an optional `enabled` column. Used when `rows` is omitted.
```bash Rows theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 }
]
}'
```
```bash CSV theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" }'
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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](/geo/content-gaps-and-writer#search-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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
]
}'
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 }
}
```
Recorded answers across every engine that responded.
How many of those answers mentioned the tracked brand.
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.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" }'
```
1 to 128 characters.
Set to rename an existing competitor.
Website domain, up to 128 characters, or `null`.
Up to 8 entries.
Defaults to `direct` when omitted on create.
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.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.usenotra.com/v1/projects/$PROJECT_ID/geo/competitors/suggestions?domain=usenotra.com" \
-H "Authorization: Bearer $NOTRA_API_KEY"
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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.
1 to 25 objects with `name` (required), `domain`, `kind`, and `synonyms` (up to 8).
Raw CSV text, up to 1 MiB, with a `name` column and optional `domain`, `kind`, `synonyms` columns. Used when `rows` is omitted.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
Full request and response schema.
Full request and response schema.