> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> Create, update, and retrieve tracked prompts and their analytics, AI responses, domains, and URLs.

Prompts are the AI search queries Topify.ai tracks daily across all AI providers. Each prompt generates responses that are analyzed for brand visibility, sentiment, citations, and competitor mentions.

The API supports creating, updating, and retrieving prompts. Prompt deletion is intentionally not exposed through the public API. API keys are issued by team admins.

## List prompts

```
GET /projects/{project_id}/prompts
```

Returns all prompts in a project, ordered by creation date.

### Path parameters

| Param        | Type          | Description    |
| ------------ | ------------- | -------------- |
| `project_id` | string (UUID) | The project ID |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts")
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "project_id": "a1b2c3d4-...",
    "total": 25,
    "prompts": [
      {
        "id": "e5f6a7b8-...",
        "project_id": "a1b2c3d4-...",
        "content": "What is the best project management tool?",
        "prompt_type": "active",
        "topic_id": "t1u2v3w4-...",
        "country": "US",
        "visibility": 85.0,
        "sentiment": 72,
        "position": 2.3,
        "volume": 150,
        "cvr": 45.0,
        "intent": "commercial",
        "trend": "up",
        "created_at": "2026-01-15T10:30:00+00:00"
      }
    ]
  }
}
```

### Prompt fields

| Field         | Type              | Nullable | Description                                                                  |
| ------------- | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `id`          | string (UUID)     | No       | Prompt ID                                                                    |
| `project_id`  | string (UUID)     | No       | Parent project ID                                                            |
| `content`     | string            | No       | The AI search query text                                                     |
| `prompt_type` | string            | No       | `active`, `suggested`, `pending`, `inactive`, or `url_recommended`           |
| `topic_id`    | string (UUID)     | Yes      | Topic this prompt belongs to                                                 |
| `country`     | string            | Yes      | Target country for localized responses                                       |
| `visibility`  | float             | Yes      | Brand visibility percentage (0--100)                                         |
| `sentiment`   | integer           | Yes      | Brand sentiment score                                                        |
| `position`    | float             | Yes      | Average brand position in responses                                          |
| `volume`      | integer           | Yes      | Number of responses collected                                                |
| `cvr`         | float             | Yes      | Content visibility rate                                                      |
| `intent`      | string            | Yes      | Query intent: `informational`, `commercial`, `navigational`, `transactional` |
| `trend`       | string            | Yes      | Trend direction: `up`, `down`, or `stable`                                   |
| `created_at`  | string (ISO 8601) | No       | Creation timestamp                                                           |

***

## Generate suggested prompts

```http theme={null}
POST /projects/{project_id}/prompts/suggested
```

Creates placeholder prompts immediately and fills their content through a background Semrush, DataForSEO, and LLM pipeline. Generation usually takes 30-90 seconds.

### Request body

<Note>
  This generation endpoint currently uses camelCase request and response fields.
</Note>

| Field              | Type    | Required | Description                                                          |
| ------------------ | ------- | -------- | -------------------------------------------------------------------- |
| `count`            | integer | No       | Number to generate, from 1 to 50; defaults to the project batch size |
| `generationMethod` | string  | No       | Currently only `keyword_seo_v1`                                      |
| `idempotencyKey`   | string  | No       | Reuse the same value to retry safely                                 |
| `functionAnalysis` | string  | No       | Precomputed site analysis used to seed generation                    |

```bash theme={null}
curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/suggested" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"count":10,"generationMethod":"keyword_seo_v1","idempotencyKey":"suggest-2026-07-13"}'
```

### Response

```json theme={null}
{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "queuedCount": 10,
    "createdCount": 10,
    "totalSuggested": 10,
    "prompts": [
      {
        "promptId": "e5f6a7b8-...",
        "content": "",
        "promptType": "Suggested",
        "generationMethod": "keyword_seo_v1",
        "createdAt": "2026-07-13T12:00:00+00:00"
      }
    ],
    "message": "10 suggested prompt generation(s) queued."
  }
}
```

Poll `GET /projects/{project_id}/prompts` and filter for `promptType=Suggested` to watch the placeholders fill in.

***

## Generate URL recommendations

```http theme={null}
POST /projects/{project_id}/prompts/url-recommendations
```

Creates prompt recommendations for one to five target URLs. Existing-match checks and new candidate generation continue in the background after placeholders are returned.

### Request body

| Field   | Type      | Required | Description                                        |
| ------- | --------- | -------- | -------------------------------------------------- |
| `urls`  | string\[] | Yes      | One to five target URLs                            |
| `count` | integer   | No       | Number of recommendations, from 1 to 20; default 5 |

```bash theme={null}
curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/url-recommendations" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://acme.com/pricing"],"count":5}'
```

### Response

```json theme={null}
{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "urlsProvided": 1,
    "dbMatches": 0,
    "placeholdersCreated": 5,
    "message": "URL-recommendations generation started."
  }
}
```

Poll the prompt list for `promptType=UrlRecommended`. Public prompt deletion and placeholder-cleanup operations are intentionally unavailable.

***

## Get prompt

```
GET /projects/{project_id}/prompts/{prompt_id}
```

Returns a single prompt. Same fields as list.

### Path parameters

| Param        | Type          | Description    |
| ------------ | ------------- | -------------- |
| `project_id` | string (UUID) | The project ID |
| `prompt_id`  | string (UUID) | The prompt ID  |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}")
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}`, { headers });
    ```
  </Tab>
</Tabs>

***

## Create prompts

```
POST /projects/{project_id}/prompts
```

Add one or more prompts to a project. Each prompt begins tracking immediately -- Topify.ai will start collecting AI responses and calculating metrics in the background.

<Warning>
  API keys are admin-created and currently have full-team access. Confirm the project and prompt text before creating prompts.
</Warning>

### Path parameters

| Param        | Type          | Description                   |
| ------------ | ------------- | ----------------------------- |
| `project_id` | string (UUID) | The project to add prompts to |

### Request body

| Field     | Type          | Required | Description                                        |
| --------- | ------------- | -------- | -------------------------------------------------- |
| `prompts` | string\[]     | Yes      | Array of prompt texts to track (1--50 per request) |
| `topicId` | string (UUID) | Yes      | Topic to assign the prompts to                     |
| `country` | string        | No       | ISO country code for localized responses           |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts" \
      -H "X-API-Key: tk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "prompts": ["What is the best project management tool?", "Top PM software for teams"],
        "topicId": "t1u2v3w4-...",
        "country": "US"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.post(f"/projects/{project_id}/prompts", json={
        "prompts": ["What is the best project management tool?"],
        "topicId": topic_id,
        "country": "US",
    })
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts`, {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({
        prompts: ["What is the best project management tool?"],
        topicId: topicId,
        country: "US",
      }),
    });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "created": 2,
    "prompts": [
      {
        "id": "e5f6a7b8-...",
        "projectId": "a1b2c3d4-...",
        "content": "What is the best project management tool?",
        "promptType": "Active",
        "topicId": "t1u2v3w4-...",
        "country": "US",
        "createdAt": "2026-03-30T10:30:00+00:00"
      }
    ]
  }
}
```

### Error responses

| Status | Cause                                                              |
| ------ | ------------------------------------------------------------------ |
| `400`  | Empty prompts array, whitespace-only content, or missing `topicId` |
| `409`  | A prompt with the same content already exists in this project      |
| `429`  | Prompt quota exceeded for your plan tier                           |

***

## Update prompt

```
PATCH /projects/{project_id}/prompts/{prompt_id}
```

Update the content, country, topic, or type of an existing prompt.

<Warning>
  API keys are admin-created and currently have full-team access. Confirm the project and fields before updating a prompt.
</Warning>

### Path parameters

| Param        | Type          | Description          |
| ------------ | ------------- | -------------------- |
| `project_id` | string (UUID) | The project ID       |
| `prompt_id`  | string (UUID) | The prompt to update |

### Request body

All fields are optional. Include only the fields you want to change.

| Field        | Type          | Description                                            |
| ------------ | ------------- | ------------------------------------------------------ |
| `content`    | string        | New prompt text (cannot be empty)                      |
| `country`    | string        | ISO country code                                       |
| `topicId`    | string (UUID) | Reassign to a different topic                          |
| `promptType` | string        | Change prompt type (`Active`, `Inactive`, `Suggested`) |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X PATCH "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}" \
      -H "X-API-Key: tk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"content": "Best project management tools for remote teams"}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.patch(f"/projects/{project_id}/prompts/{prompt_id}", json={
        "content": "Best project management tools for remote teams",
    })
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}`, {
      method: "PATCH",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ content: "Best project management tools for remote teams" }),
    });
    ```
  </Tab>
</Tabs>

### Response

Returns the updated prompt with all fields (same shape as [get prompt](#get-prompt)).

### Error responses

| Status | Cause                                                             |
| ------ | ----------------------------------------------------------------- |
| `400`  | Empty request body, whitespace-only content, or no fields changed |
| `404`  | Prompt not found in this project                                  |

***

## Prompt analytics

```
GET /projects/{project_id}/prompts/{prompt_id}/analytics
```

Returns time-series visibility, position, and sentiment data grouped by date and AI provider.

### Query parameters

| Param           | Type    | Default | Description                     |
| --------------- | ------- | ------- | ------------------------------- |
| `duration_days` | integer | `7`     | Days to look back               |
| `date_from`     | string  | --      | Start date (`YYYY-MM-DD`)       |
| `date_to`       | string  | --      | End date (`YYYY-MM-DD`)         |
| `providers`     | string  | --      | Comma-separated provider filter |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/analytics?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/analytics", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/analytics?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "prompt_id": "e5f6a7b8-...",
    "prompt_content": "What is the best project management tool?",
    "volume": 42,
    "sentiment": 72,
    "visibility_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 85.0 },
        { "provider": "perplexity", "value": 90.0 }
      ],
      "2026-03-02": [
        { "provider": "chatgpt", "value": 80.0 }
      ]
    },
    "position_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 2.0 }
      ]
    },
    "sentiment_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 75.0 }
      ]
    }
  }
}
```

### Response fields

| Field              | Type          | Nullable | Description                                          |
| ------------------ | ------------- | -------- | ---------------------------------------------------- |
| `prompt_id`        | string (UUID) | No       | Prompt ID                                            |
| `prompt_content`   | string        | No       | The AI search query text                             |
| `volume`           | integer       | Yes      | Total responses collected                            |
| `sentiment`        | integer       | Yes      | Overall brand sentiment across the period            |
| `visibility_chart` | object        | No       | Date-keyed map of `ProviderMetric[]` (visibility %)  |
| `position_chart`   | object        | No       | Date-keyed map of `ProviderMetric[]` (avg position)  |
| `sentiment_chart`  | object        | No       | Date-keyed map of `ProviderMetric[]` (avg sentiment) |

**ProviderMetric:**

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| `provider` | string | AI provider name (e.g., `chatgpt`)          |
| `value`    | float  | Metric value for that provider on that date |

***

## Prompt competitor metrics

```
GET /projects/{project_id}/prompts/{prompt_id}/competitors
```

Returns prompt-scoped metrics for every active competitor under a single prompt. Use this endpoint to export each brand's visibility, sentiment, position, and share of voice for one prompt without opening the dashboard prompt detail page.

The response is computed from raw AI responses for the selected prompt and date range.

### Path parameters

| Param        | Type          | Description    |
| ------------ | ------------- | -------------- |
| `project_id` | string (UUID) | The project ID |
| `prompt_id`  | string (UUID) | The prompt ID  |

### Query parameters

| Param                 | Type    | Default | Description                                                                                                 |
| --------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `duration_days`       | integer | `30`    | Days to look back when no explicit date range is provided                                                   |
| `date_from`           | string  | --      | Start date (`YYYY-MM-DD`)                                                                                   |
| `date_to`             | string  | --      | End date (`YYYY-MM-DD`)                                                                                     |
| `providers`           | string  | --      | Comma-separated provider filter                                                                             |
| `aggregate_over_time` | boolean | `true`  | `true` returns one row per competitor for the whole period. `false` returns one row per competitor per day. |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/competitors?duration_days=7&aggregate_over_time=false" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(
        f"/projects/{project_id}/prompts/{prompt_id}/competitors",
        params={"duration_days": 7, "aggregate_over_time": False},
    )
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(
      `${BASE}/projects/${projectId}/prompts/${promptId}/competitors?duration_days=7&aggregate_over_time=false`,
      { headers }
    );
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "prompt_id": "e5f6a7b8-...",
    "prompt_content": "What are the best luxury cake brands for gifting online?",
    "period": {
      "date_from": "2026-03-01",
      "date_to": "2026-03-07"
    },
    "aggregate_over_time": false,
    "granularity": "day",
    "items": [
      {
        "date": "2026-03-01",
        "competitor_id": "00000000-0000-0000-0000-000000000000",
        "project_id": "a1b2c3d4-...",
        "name": "Acme Corp",
        "website": "https://acme.com",
        "icon_url": "https://logo.clearbit.com/acme.com",
        "icon_urls": [
          "https://logo.clearbit.com/acme.com",
          "https://www.google.com/s2/favicons?domain=acme.com&sz=64"
        ],
        "state": "active",
        "is_own_brand": true,
        "visibility": 54.55,
        "sentiment": 76.9,
        "position": 2.83,
        "sov": 9.3,
        "mention_count": 12,
        "total_responses": 22,
        "total_brand_mentions": 129,
        "sentiment_count": 10,
        "position_count": 12,
        "days_with_data": 1,
        "days_with_responses": 1
      }
    ],
    "total_items": 77,
    "total_competitors": 11
  }
}
```

### PromptCompetitorsResponse fields

| Field                 | Type                          | Nullable | Description                                                     |
| --------------------- | ----------------------------- | -------- | --------------------------------------------------------------- |
| `prompt_id`           | string (UUID)                 | No       | Prompt ID                                                       |
| `prompt_content`      | string                        | No       | The AI search query text                                        |
| `period`              | object                        | No       | Date range used for the calculation                             |
| `aggregate_over_time` | boolean                       | No       | Whether rows are aggregated across the whole period             |
| `granularity`         | string                        | No       | `period` when aggregated, or `day` when daily rows are returned |
| `items`               | PromptCompetitorMetricItem\[] | No       | Competitor metric rows                                          |
| `total_items`         | integer                       | No       | Number of rows in `items`                                       |
| `total_competitors`   | integer                       | No       | Number of active competitors included                           |

### PromptCompetitorMetricItem fields

| Field                  | Type          | Nullable | Description                                                              |
| ---------------------- | ------------- | -------- | ------------------------------------------------------------------------ |
| `date`                 | string        | Yes      | Date in `YYYY-MM-DD` format. `null` when `aggregate_over_time=true`      |
| `competitor_id`        | string (UUID) | No       | Competitor ID. `00000000-...` for injected own brand                     |
| `project_id`           | string (UUID) | No       | Parent project ID                                                        |
| `name`                 | string        | No       | Competitor brand name                                                    |
| `website`              | string        | No       | Competitor website URL                                                   |
| `icon_url`             | string        | Yes      | Primary logo URL                                                         |
| `icon_urls`            | string\[]     | No       | Multiple logo URL sources                                                |
| `state`                | string        | Yes      | Competitor state, usually `active`                                       |
| `is_own_brand`         | boolean       | No       | `true` if this row is your own brand                                     |
| `visibility`           | float         | Yes      | Percentage of prompt responses that mention this competitor              |
| `sentiment`            | float         | Yes      | Average sentiment score for this competitor                              |
| `position`             | float         | Yes      | Average ranked position when this competitor is mentioned                |
| `sov`                  | float         | Yes      | Share of voice: this competitor's mentions divided by all brand mentions |
| `mention_count`        | integer       | No       | Number of prompt responses where this competitor was mentioned           |
| `total_responses`      | integer       | No       | Number of prompt responses in the row's date bucket or period            |
| `total_brand_mentions` | integer       | No       | Number of all brand mentions in the row's date bucket or period          |
| `sentiment_count`      | integer       | No       | Number of sentiment observations used in `sentiment`                     |
| `position_count`       | integer       | No       | Number of position observations used in `position`                       |
| `days_with_data`       | integer       | No       | Number of days where this competitor was mentioned                       |
| `days_with_responses`  | integer       | No       | Number of days with prompt responses                                     |

<Note>
  With `aggregate_over_time=true`, `date` is `null` and each row covers the full `period`. With `aggregate_over_time=false`, `items` contains one row for each date and competitor. `visibility` is `0.0` when prompt responses exist but the competitor was not mentioned, and `null` when the prompt has no responses in that bucket. `sentiment`, `position`, and `sov` are `null` when there is no observation or denominator for that metric.
</Note>

***

## AI responses (chats)

```
GET /projects/{project_id}/prompts/{prompt_id}/chats
```

Returns raw AI responses with brand mentions, sentiment, position, and citation references.

### Query parameters

Same as [analytics](#prompt-analytics).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/chats?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/chats", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/chats?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "c1d2e3f4-...",
        "date": "2026-03-01T12:00:00+00:00",
        "mentioned": true,
        "position": 2,
        "all_mentions": [
          {
            "name": "Acme Corp",
            "icon_url": "https://logo.clearbit.com/acme.com",
            "icon_urls": ["https://logo.clearbit.com/acme.com", "https://www.google.com/s2/favicons?domain=acme.com&sz=64"]
          }
        ],
        "chat_preview": "When it comes to project management tools...",
        "platform": "chatgpt",
        "model": "gpt-4o",
        "full_content": "When it comes to project management tools, Acme Corp stands out for...",
        "prompt_content": "What is the best project management tool?",
        "references": [
          {
            "title": "Best PM Tools 2026",
            "link": "https://techcrunch.com/best-pm-tools",
            "snippet": "Acme Corp ranked #1...",
            "reference_index": 1
          }
        ],
        "brands_mentioned": {
          "Acme Corp": { "position": 1, "count": 3 },
          "Competitor A": { "position": 2, "count": 1 }
        },
        "sentiment": 80,
        "sentiment_by_brands": {
          "Acme Corp": 80,
          "Competitor A": 60
        }
      }
    ]
  }
}
```

### ChatItem fields

| Field                 | Type              | Nullable | Description                                                                     |
| --------------------- | ----------------- | -------- | ------------------------------------------------------------------------------- |
| `id`                  | string (UUID)     | No       | LLM output ID                                                                   |
| `date`                | string (ISO 8601) | No       | When the response was generated                                                 |
| `mentioned`           | boolean           | No       | Whether your brand was mentioned                                                |
| `position`            | integer           | Yes      | Your brand's rank position in this response                                     |
| `all_mentions`        | BrandMention\[]   | No       | All brands mentioned in the response                                            |
| `chat_preview`        | string            | No       | First sentence of the response (max 150 chars)                                  |
| `platform`            | string            | No       | AI provider (`chatgpt`, `perplexity`, `google_ai_overview`, `gemini`, `claude`) |
| `model`               | string            | No       | Specific model used (e.g., `gpt-4o`)                                            |
| `full_content`        | string            | No       | Complete AI response text                                                       |
| `prompt_content`      | string            | No       | The prompt that generated this response                                         |
| `references`          | ReferenceItem\[]  | No       | Citations/sources in the response                                               |
| `brands_mentioned`    | object            | Yes      | Raw brand extraction data (brand name to position/count mapping)                |
| `sentiment`           | integer           | Yes      | Your brand's sentiment score in this response                                   |
| `sentiment_by_brands` | object            | Yes      | Sentiment scores keyed by brand name                                            |

**BrandMention:**

| Field       | Type      | Description                               |
| ----------- | --------- | ----------------------------------------- |
| `name`      | string    | Brand name as it appeared in the response |
| `icon_url`  | string    | Primary logo URL                          |
| `icon_urls` | string\[] | Multiple logo URL sources                 |

**ReferenceItem:**

| Field             | Type    | Description                              |
| ----------------- | ------- | ---------------------------------------- |
| `title`           | string  | Citation title                           |
| `link`            | string  | Citation URL                             |
| `snippet`         | string  | Citation snippet text                    |
| `reference_index` | integer | Position of the citation in the response |

***

## Domains

```
GET /projects/{project_id}/prompts/{prompt_id}/domains
```

Returns domain-level citation breakdown, sorted by citation count descending.

### Query parameters

Same as [analytics](#prompt-analytics).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/domains?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/domains", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/domains?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "domain": "techcrunch.com",
        "domain_type": 1,
        "citation_count": 15,
        "avg_citations": 2.5,
        "used_percentage": 75.0,
        "mentioned": true,
        "brands_appeared": [
          {
            "name": "Acme Corp",
            "icon_url": "https://logo.clearbit.com/acme.com",
            "icon_urls": ["https://logo.clearbit.com/acme.com"]
          }
        ],
        "favicon_url": "https://www.google.com/s2/favicons?domain=techcrunch.com&sz=64",
        "favicon_urls": [
          "https://logo.clearbit.com/techcrunch.com",
          "https://www.google.com/s2/favicons?domain=techcrunch.com&sz=64"
        ]
      }
    ]
  }
}
```

### DomainItem fields

| Field             | Type         | Nullable | Description                                           |
| ----------------- | ------------ | -------- | ----------------------------------------------------- |
| `domain`          | string       | No       | Domain name                                           |
| `domain_type`     | integer      | No       | Source category ID                                    |
| `citation_count`  | integer      | No       | Total citation count across all responses             |
| `avg_citations`   | float        | No       | Average citations per response that cited this domain |
| `used_percentage` | float        | No       | How frequently this domain appears (percentage)       |
| `mentioned`       | boolean      | No       | Whether your brand appeared alongside this domain     |
| `brands_appeared` | BrandInfo\[] | No       | Brands that appeared in responses citing this domain  |
| `favicon_url`     | string       | Yes      | Primary favicon URL                                   |
| `favicon_urls`    | string\[]    | No       | Multiple favicon URL sources                          |

**BrandInfo:**

| Field       | Type      | Description               |
| ----------- | --------- | ------------------------- |
| `name`      | string    | Brand name                |
| `icon_url`  | string    | Primary logo URL          |
| `icon_urls` | string\[] | Multiple logo URL sources |

***

## URLs

```
GET /projects/{project_id}/prompts/{prompt_id}/urls
```

Returns URL-level citation data, sorted by mention count descending.

### Query parameters

Same as [analytics](#prompt-analytics).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/urls?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/urls", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/urls?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "url": "https://techcrunch.com/best-pm-tools-2026",
        "title": "Best PM Tools 2026",
        "domain": "techcrunch.com",
        "url_type": null,
        "url_type_name": "unknown",
        "mentioned_count": 8,
        "brands_appear": [
          {
            "name": "Acme Corp",
            "icon_url": "https://logo.clearbit.com/acme.com",
            "icon_urls": ["https://logo.clearbit.com/acme.com"]
          }
        ],
        "first_seen": "2026-02-15T00:00:00+00:00",
        "last_seen": "2026-03-01T00:00:00+00:00"
      }
    ]
  }
}
```

### UrlItem fields

| Field             | Type              | Nullable | Description                                       |
| ----------------- | ----------------- | -------- | ------------------------------------------------- |
| `url`             | string            | No       | Full URL                                          |
| `title`           | string            | No       | Page title                                        |
| `domain`          | string            | No       | Domain extracted from URL                         |
| `url_type`        | integer           | Yes      | URL type ID                                       |
| `url_type_name`   | string            | No       | URL type label (e.g., `unknown`)                  |
| `mentioned_count` | integer           | No       | Number of times this URL was cited                |
| `brands_appear`   | BrandInfo\[]      | No       | Brands appearing in responses that cited this URL |
| `first_seen`      | string (ISO 8601) | No       | Earliest citation date                            |
| `last_seen`       | string (ISO 8601) | No       | Most recent citation date                         |