### Authentication Example

Source: https://docs.useomnia.com/api/index

Example of how to authenticate API requests using a Bearer token in the Authorization header.

```APIDOC
## Authentication

Authenticate by including your API key in every request. You can generate and manage keys from the API access page.

Include the key in the `Authorization` header:

```bash
curl https://app.useomnia.com/api/v1/brands \
  -H "Authorization: Bearer ot_your-token-here"
```

> **Treat your API keys like passwords.** Never commit them to version control or expose them in frontend code. If a key leaks, revoke it immediately from your API access page.
```

--------------------------------

### GET /api/v1/brands

Source: https://docs.useomnia.com/api/index

Retrieves a list of brands. Supports pagination.

```APIDOC
## GET /api/v1/brands

### Description
Retrieves a list of brands. Supports pagination.

### Method
GET

### Endpoint
/api/v1/brands

### Query Parameters
- **page** (integer) - Optional - Which page to fetch (starts at 1)
- **pageSize** (integer) - Optional - Items per page (5–100)

### Request Example
```bash
curl "https://app.useomnia.com/api/v1/brands?page=2&pageSize=20" \
  -H "Authorization: Bearer ot_your-token-here"
```

### Response
#### Success Response (200)
- **data** (array) - A list of brand objects.
- **pagination** (object) - Pagination details.
- **links** (object) - Navigation links for pagination.

#### Response Example
```json
{
  "data": [
    { "id": "brand_abc", "name": "Brand A" },
    { "id": "brand_def", "name": "Brand B" }
  ],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "totalItems": 85
  },
  "links": {
    "prev": "https://app.useomnia.com/api/v1/brands?page=1&pageSize=20",
    "next": "https://app.useomnia.com/api/v1/brands?page=3&pageSize=20"
  }
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}

Source: https://docs.useomnia.com/api/index

Retrieves details for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}

### Description
Retrieves details for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Details of the topic.
- **data.id** (string) - The unique identifier for the topic.
- **data.name** (string) - The name of the topic.

#### Response Example
```json
{
  "data": {
    "id": "topic_1",
    "name": "Digital Marketing Trends"
  }
}
```
```

--------------------------------

### GET /api/v1/brands

Source: https://docs.useomnia.com/api/index

Lists all brands associated with the authenticated user.

```APIDOC
## GET /api/v1/brands

### Description
Lists all brands associated with the authenticated user.

### Method
GET

### Endpoint
/api/v1/brands

### Parameters
#### Path Parameters
None

#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **pageSize** (integer) - Optional - The number of items to return per page.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
(Response schema not provided in the input text)

#### Response Example
(Response example not provided in the input text)
```

--------------------------------

### GET /api/v1/prompts/{prompt}/visibility/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated visibility data for a specific prompt.

```APIDOC
## GET /api/v1/prompts/{prompt}/visibility/aggregates

### Description
Retrieves aggregated visibility data for a specific prompt.

### Method
GET

### Endpoint
/api/v1/prompts/{prompt}/visibility/aggregates

### Parameters
#### Path Parameters
- **prompt** (string) - Required - The unique identifier for the prompt.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/prompts/your_prompt_id/visibility/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated visibility metrics for the prompt.
- **data.visibilityScore** (number) - The overall visibility score.

#### Response Example
```json
{
  "data": {
    "visibilityScore": 60.0
  }
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}/prompts

Source: https://docs.useomnia.com/api/index

Retrieves a list of prompts associated with a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/prompts

### Description
Retrieves a list of prompts associated with a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/prompts

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/prompts \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - A list of prompts.
- **data[].id** (string) - The unique identifier for the prompt.
- **data[].name** (string) - The name of the prompt.

#### Response Example
```json
{
  "data": [
    {"id": "prompt_1", "name": "Example Prompt 1"},
    {"id": "prompt_2", "name": "Example Prompt 2"}
  ]
}
```
```

--------------------------------

### GET /api/v1/prompts/{prompt}/visibility/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series visibility data for a specific prompt.

```APIDOC

```

--------------------------------

### GET /api/v1/topics/{topic}/visibility/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series visibility data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/visibility/timeseries

### Description
Retrieves time-series visibility data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/visibility/timeseries

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/visibility/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with visibility data.
- **data[].date** (string) - The date of the data point.
- **data[].visibilityScore** (number) - The visibility score for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "visibilityScore": 65.0},
    {"date": "2023-01-02", "visibilityScore": 67.5}
  ]
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}

Source: https://docs.useomnia.com/api/index

Retrieves a specific brand by its ID.

```APIDOC
## GET /api/v1/brands/{brand}

### Description
Retrieves a specific brand by its ID.

### Method
GET

### Endpoint
/api/v1/brands/{brand}

### Path Parameters
- **brand** (string) - Required - The ID of the brand to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The requested brand object.

#### Response Example
```json
{
  "data": {
    "id": "brand_abc123",
    "name": "My Brand"
  }
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}/citations/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series citation data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/citations/timeseries

### Description
Retrieves time-series citation data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/citations/timeseries

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/citations/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with citation data.
- **data[].date** (string) - The date of the data point.
- **data[].citationCount** (integer) - The number of citations for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "citationCount": 10},
    {"date": "2023-01-02", "citationCount": 12}
  ]
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}/visibility/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series visibility data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/visibility/timeseries

### Description
Retrieves time-series visibility data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/visibility/timeseries

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/visibility/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with visibility data.
- **data[].date** (string) - The date of the data point.
- **data[].visibilityScore** (number) - The visibility score for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "visibilityScore": 80.0},
    {"date": "2023-01-02", "visibilityScore": 81.2}
  ]
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}/citations/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series citation data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/citations/timeseries

### Description
Retrieves time-series citation data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/citations/timeseries

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/citations/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with citation data.
- **data[].date** (string) - The date of the data point.
- **data[].citationCount** (integer) - The number of citations for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "citationCount": 5},
    {"date": "2023-01-02", "citationCount": 7}
  ]
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}/citations/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated citation data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/citations/aggregates

### Description
Retrieves aggregated citation data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/citations/aggregates

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/citations/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated citation metrics for the topic.
- **data.citationCount** (integer) - The total number of citations.

#### Response Example
```json
{
  "data": {
    "citationCount": 300
  }
}
```
```

--------------------------------

### POST /api/v1/trends/{trend}/accept

Source: https://docs.useomnia.com/api/index

Accepts a trend and starts monitoring all the selected prompt ids. This converts the trend into an active topic that can be managed via the topics endpoints.

```APIDOC
## POST /api/v1/trends/{trend}/accept

### Description
Accepts a trend and starts monitoring all the selected prompt ids. This converts the trend into an active topic that can be managed via the topics endpoints.

### Method
POST

### Endpoint
/api/v1/trends/{trend}/accept

### Parameters
#### Path Parameters
- **trend** (string) - Required - Unique identifier for the trend

#### Query Parameters
None

#### Request Body
- **promptIds** (array of strings) - Required - A list of prompt IDs to monitor for the trend.

### Request Example
```json
{
  "promptIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the ID of the newly created topic.
  - **topicId** (string) - The unique identifier for the created topic.

#### Response Example
```json
{
  "data": {
    "topicId": "550e8400-e29b-41d4-a716-446655440001"
  }
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}/citations/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated citation data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/citations/aggregates

### Description
Retrieves aggregated citation data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/citations/aggregates

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/citations/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated citation metrics.
- **data.citationCount** (integer) - The total number of citations.
- **data.domains** (array) - A list of domains associated with the citations.

#### Response Example
```json
{
  "data": {
    "citationCount": 500,
    "domains": ["example.com", "anotherexample.net"]
  }
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}/visibility/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated visibility data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/visibility/aggregates

### Description
Retrieves aggregated visibility data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/visibility/aggregates

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/visibility/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated visibility metrics.
- **data.visibilityScore** (number) - The overall visibility score.
- **data.domains** (array) - A list of domains associated with the visibility.

#### Response Example
```json
{
  "data": {
    "visibilityScore": 85.5,
    "domains": ["example.com", "anotherexample.net"]
  }
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}/visibility/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated visibility data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/visibility/aggregates

### Description
Retrieves aggregated visibility data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/visibility/aggregates

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/visibility/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated visibility metrics for the topic.
- **data.visibilityScore** (number) - The overall visibility score.

#### Response Example
```json
{
  "data": {
    "visibilityScore": 70.0
  }
}
```
```

--------------------------------

### GET /api/v1/prompts/{prompt}/share-of-voice/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series share of voice data for a specific prompt.

```APIDOC
## GET /api/v1/prompts/{prompt}/share-of-voice/timeseries

### Description
Retrieves time-series share of voice data for a specific prompt.

### Method
GET

### Endpoint
/api/v1/prompts/{prompt}/share-of-voice/timeseries

### Parameters
#### Path Parameters
- **prompt** (string) - Required - The unique identifier for the prompt.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/prompts/your_prompt_id/share-of-voice/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with share of voice data.
- **data[].date** (string) - The date of the data point.
- **data[].shareOfVoice** (number) - The share of voice percentage for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "shareOfVoice": 0.35},
    {"date": "2023-01-02", "shareOfVoice": 0.38}
  ]
}
```
```

--------------------------------

### GET /api/v1/prompts/{prompt}/share-of-voice/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated share of voice data for a specific prompt.

```APIDOC
## GET /api/v1/prompts/{prompt}/share-of-voice/aggregates

### Description
Retrieves aggregated share of voice data for a specific prompt.

### Method
GET

### Endpoint
/api/v1/prompts/{prompt}/share-of-voice/aggregates

### Parameters
#### Path Parameters
- **prompt** (string) - Required - The unique identifier for the prompt.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/prompts/your_prompt_id/share-of-voice/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated share of voice metrics for the prompt.
- **data.shareOfVoice** (number) - The share of voice percentage.
- **data.mentioned** (number) - The number of mentions.

#### Response Example
```json
{
  "data": {
    "shareOfVoice": 0.40,
    "mentioned": 150
  }
}
```
```

--------------------------------

### GET /api/v1/topics/{topic}/share-of-voice/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated share of voice data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/share-of-voice/aggregates

### Description
Retrieves aggregated share of voice data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/share-of-voice/aggregates

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/share-of-voice/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated share of voice metrics for the topic.
- **data.shareOfVoice** (number) - The share of voice percentage.
- **data.mentioned** (number) - The number of mentions.

#### Response Example
```json
{
  "data": {
    "shareOfVoice": 0.60,
    "mentioned": 200
  }
}
```
```

--------------------------------

### Paginated API Response Structure

Source: https://docs.useomnia.com/api/index

Example of a paginated response from the Omnia API, including the data array, pagination metadata, and navigation links. This structure facilitates easy traversal through multiple pages of results.

```json
{
  "data": [
    { "id": "brand_abc", "name": "Brand A" },
    { "id": "brand_def", "name": "Brand B" }
  ],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "totalItems": 85
  },
  "links": {
    "prev": "https://app.useomnia.com/api/v1/brands?page=1&pageSize=20",
    "next": "https://app.useomnia.com/api/v1/brands?page=3&pageSize=20"
  }
}
```

--------------------------------

### GET /api/v1/topics/{topic}/share-of-voice/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series share of voice data for a specific topic.

```APIDOC
## GET /api/v1/topics/{topic}/share-of-voice/timeseries

### Description
Retrieves time-series share of voice data for a specific topic.

### Method
GET

### Endpoint
/api/v1/topics/{topic}/share-of-voice/timeseries

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/topics/your_topic_id/share-of-voice/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with share of voice data.
- **data[].date** (string) - The date of the data point.
- **data[].shareOfVoice** (number) - The share of voice percentage for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "shareOfVoice": 0.55},
    {"date": "2023-01-02", "shareOfVoice": 0.58}
  ]
}
```
```

--------------------------------

### Get AI Answer by ID

Source: https://docs.useomnia.com/api/index

Retrieves a specific AI-generated answer using its unique identifier. Requires an API key for authorization. Returns the answer content, citations, and metadata.

```shell
curl 'https://app.useomnia.com/api/v1/ai-answers/{ai-answer}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /api/v1/brands/{brand}/share-of-voice/aggregates

Source: https://docs.useomnia.com/api/index

Retrieves aggregated share of voice data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/share-of-voice/aggregates

### Description
Retrieves aggregated share of voice data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/share-of-voice/aggregates

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/share-of-voice/aggregates \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the aggregated share of voice metrics.
- **data.shareOfVoice** (number) - The share of voice percentage.
- **data.mentioned** (number) - The number of mentions.
- **data.domains** (array) - A list of domains associated with the share of voice.

#### Response Example
```json
{
  "data": {
    "shareOfVoice": 0.75,
    "mentioned": 150,
    "domains": ["example.com", "anotherexample.net"]
  }
}
```
```

--------------------------------

### GET /api/v1/brands/{brand}/share-of-voice/timeseries

Source: https://docs.useomnia.com/api/index

Retrieves time-series share of voice data for a specific brand.

```APIDOC
## GET /api/v1/brands/{brand}/share-of-voice/timeseries

### Description
Retrieves time-series share of voice data for a specific brand.

### Method
GET

### Endpoint
/api/v1/brands/{brand}/share-of-voice/timeseries

### Parameters
#### Path Parameters
- **brand** (string) - Required - The unique identifier for the brand.

#### Query Parameters
- **startDate** (string) - Optional - The start date for the time series (ISO 8601 format).
- **endDate** (string) - Optional - The end date for the time series (ISO 8601 format).

### Request Example
```
curl -X GET https://app.useomnia.com/api/v1/brands/your_brand_id/share-of-voice/timeseries?startDate=2023-01-01&endDate=2023-12-31 \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a time point with share of voice data.
- **data[].date** (string) - The date of the data point.
- **data[].shareOfVoice** (number) - The share of voice percentage for that date.

#### Response Example
```json
{
  "data": [
    {"date": "2023-01-01", "shareOfVoice": 0.70},
    {"date": "2023-01-02", "shareOfVoice": 0.72}
  ]
}
```
```

--------------------------------

### Get AI Answer by ID

Source: https://docs.useomnia.com/api/index

Retrieves a specific AI-generated answer using its unique identifier.

```APIDOC
## GET /api/v1/ai-answers/{ai-answer}

### Description
Retrieve an AI answer by its ID.

### Method
GET

### Endpoint
/api/v1/ai-answers/{ai-answer}

#### Path Parameters
- **ai-answer** (string) - Required - Unique identifier for the AI answer.

### Request Example
```bash
curl 'https://app.useomnia.com/api/v1/ai-answers/{ai-answer}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (object) - Contains the AI answer details.
  - **answer** (string) - The AI-generated answer.
  - **citations** (array) - List of citations used for the answer.
    - **title** (string) - The title of the citation.
    - **url** (string) - The URL of the citation.
  - **createdAt** (string) - The timestamp when the answer was created (ISO 8601 format).
  - **engine** (string) - The AI engine used to generate the answer.
  - **id** (integer) - The unique identifier for the AI answer.
  - **mentioned** (boolean) - Indicates if any brands were mentioned.
  - **mentionedBrands** (array) - List of brands mentioned in the answer.
    - (string) - The name of the mentioned brand.
  - **promptId** (string) - The ID of the prompt that generated this answer.
  - **query** (string) - The original query that led to this answer.

#### Response Example
```json
{
  "data": {
    "answer": "Based on my analysis, the best software for small businesses includes Brand 1, Brand 2, and Brand 3...",
    "citations": [
      {
        "title": "Best Software 2026 | Acme Reviews",
        "url": "https://example.com/software-reviews"
      }
    ],
    "createdAt": "2026-01-01T09:30:00Z",
    "engine": "openai",
    "id": 12345,
    "mentioned": true,
    "mentionedBrands": [
      "Brand 1",
      "Brand 2",
      "Brand 3"
    ],
    "promptId": "550e8400-e29b-41d4-a716-446655440000",
    "query": "What is the best software for small businesses?"
  }
}
```

#### Error Responses
- **400** Bad request
- **401** Unauthorized
- **404** Item not found
- **500** Internal server error
```

--------------------------------

### Making Requests

Source: https://docs.useomnia.com/api/index

Information on how to make requests to the Omnia API, including the base URL and content type for requests with a body.

```APIDOC
## Making requests

Send all requests to:

```
https://app.useomnia.com/api/v1
```

For requests with a body (e.g. `POST`, `PUT`, `PATCH`), send a JSON formatted body, and set the appropriate `Content-Type: application/json` header.
```

--------------------------------

### POST /api/v1/topics/{topic}/prompts

Source: https://docs.useomnia.com/api/index

Creates a new prompt for a specific topic.

```APIDOC
## POST /api/v1/topics/{topic}/prompts

### Description
Creates a new prompt for a specific topic.

### Method
POST

### Endpoint
/api/v1/topics/{topic}/prompts

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

#### Request Body
- **name** (string) - Required - The name of the new prompt.
- **promptText** (string) - Required - The text content of the prompt.

### Request Example
```json
{
  "name": "New Marketing Prompt",
  "promptText": "Analyze the latest marketing campaign performance."
}
```

### Response
#### Success Response (201)
- **data** (object) - The newly created prompt.
- **data.id** (string) - The unique identifier for the prompt.
- **data.name** (string) - The name of the prompt.

#### Response Example
```json
{
  "data": {
    "id": "prompt_3",
    "name": "New Marketing Prompt"
  }
}
```
```

--------------------------------

### POST /api/v1/brands

Source: https://docs.useomnia.com/api/index

Creates a new brand.

```APIDOC
## POST /api/v1/brands

### Description
Creates a new brand.

### Method
POST

### Endpoint
/api/v1/brands

### Request Body
- **name** (string) - Required - The name of the brand.

### Request Example
```json
{
  "name": "New Brand Name"
}
```

### Response
#### Success Response (200)
- **data** (object) - The newly created brand object.

#### Response Example
```json
{
  "data": {
    "id": "brand_xyz789",
    "name": "New Brand Name"
  }
}
```
```

--------------------------------

### Retrieve AI Answers for a Prompt (Shell)

Source: https://docs.useomnia.com/api/index

This snippet demonstrates how to retrieve a paginated list of AI answers for a specific prompt using a cURL command. It includes parameters for date filtering and requires an authorization token. Note that pagination accuracy may vary.

```shell
curl 'https://app.useomnia.com/api/v1/prompts/550e8400-e29b-41d4-a716-446655440000/ai-answers?startDate=2026-01-01&endDate=2026-01-31' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### Versioning

Source: https://docs.useomnia.com/api/index

Information on how the Omnia API is versioned and how to include the version in API requests.

```APIDOC
# Versioning
The API version must be included in the URL path (`/api/v1/...`). When we make breaking changes, we'll release a new version and give you time to migrate before deprecating the old one.
```

--------------------------------

### Accept Trend and Monitor Prompts (cURL)

Source: https://docs.useomnia.com/api/index

Accepts a trend, converting it into an active topic and initiating monitoring for specified prompt IDs. This action requires a trend ID and an array of prompt IDs. The response includes the newly created topic ID.

```Shell
curl https://app.useomnia.com/api/v1/trends/550e8400-e29b-41d4-a716-446655440000/accept \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "promptIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}'
```

--------------------------------

### Paginate API Request with cURL

Source: https://docs.useomnia.com/api/index

Shows how to paginate results from the Omnia API by specifying 'page' and 'pageSize' query parameters. This allows for efficient retrieval of large datasets.

```shell
curl "https://app.useomnia.com/api/v1/brands?page=2&pageSize=20" \
  -H "Authorization: Bearer ot_your-token-here"
```

--------------------------------

### Import Trends using Keywords (cURL)

Source: https://docs.useomnia.com/api/index

Creates new trends by importing a list of keywords for a specified brand. This is an asynchronous operation. It requires a brand ID, country code, and a comma-separated list of keywords. The response indicates the number of trends imported and skipped.

```Shell
curl https://app.useomnia.com/api/v1/brands/550e8400-e29b-41d4-a716-446655440000/trends \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "country": "us",
  "keywords": "software,tooling,tech"
}'
```

--------------------------------

### Pagination

Source: https://docs.useomnia.com/api/index

Information on how to paginate through results, including available query parameters and response structure.

```APIDOC
# Pagination
Endpoints that return multiple items are properly paginated. You can control pagination with these query parameters: 
Parameter | Description | Default  
---|---|---
`page` | Which page to fetch (starts at 1) | `1`  
`pageSize` | Items per page (5–100) | `20`  

```bash
curl "https://app.useomnia.com/api/v1/brands?page=2&pageSize=20" \
  -H "Authorization: Bearer ot_your-token-here"
```

All paginated responses include page and navigation info alongside the results:

```json
{
  "data": [
    { "id": "brand_abc", "name": "Brand A" },
    { "id": "brand_def", "name": "Brand B" }
  ],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "totalItems": 85
  },
  "links": {
    "prev": "https://app.useomnia.com/api/v1/brands?page=1&pageSize=20",
    "next": "https://app.useomnia.com/api/v1/brands?page=3&pageSize=20"
  }
}
```

Use the URLs in `links` to move between pages rather than building them yourself.
```

--------------------------------

### List Brand Trends

Source: https://docs.useomnia.com/api/index

Retrieves a paginated list of trends for a specified brand. Supports filtering by various parameters such as location, status, and topic type. Requires brand ID and an API key.

```shell
curl https://app.useomnia.com/api/v1/brands/550e8400-e29b-41d4-a716-446655440000/trends \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### Authenticate API Request with cURL

Source: https://docs.useomnia.com/api/index

Demonstrates how to authenticate an API request to the Omnia API using a Bearer token in the Authorization header. This is a common method for securing API interactions.

```shell
curl https://app.useomnia.com/api/v1/brands \
  -H "Authorization: Bearer ot_your-token-here"
```

--------------------------------

### Error Codes Reference

Source: https://docs.useomnia.com/api/index

A reference table for all possible API error codes and their descriptions.

```APIDOC
### Error codes reference
Code | Description  
---|---
`1001` | Internal error  
`1002` | Invalid input parameters  
`1003` | Authentication configuration error  
`1004` | Invalid or expired API token  
`1005` | Missing authorization header. Please provide a Bearer token.  
`1006` | Item not found  
`1007` | Too many requests  
`1008` | Duplicated item  
`1009` | Monitoring limit exceeded  
```

--------------------------------

### PUT /api/v1/brands/{brand}

Source: https://docs.useomnia.com/api/index

Updates an existing brand.

```APIDOC
## PUT /api/v1/brands/{brand}

### Description
Updates an existing brand.

### Method
PUT

### Endpoint
/api/v1/brands/{brand}

### Path Parameters
- **brand** (string) - Required - The ID of the brand to update.

### Request Body
- **name** (string) - Optional - The new name for the brand.

### Request Example
```json
{
  "name": "Updated Brand Name"
}
```

### Response
#### Success Response (200)
- **data** (object) - The updated brand object.

#### Response Example
```json
{
  "data": {
    "id": "brand_abc123",
    "name": "Updated Brand Name"
  }
}
```
```

--------------------------------

### PUT /api/v1/topics/{topic}/toggle-monitoring

Source: https://docs.useomnia.com/api/index

Toggles the monitoring status for a specific topic.

```APIDOC
## PUT /api/v1/topics/{topic}/toggle-monitoring

### Description
Toggles the monitoring status for a specific topic.

### Method
PUT

### Endpoint
/api/v1/topics/{topic}/toggle-monitoring

### Parameters
#### Path Parameters
- **topic** (string) - Required - The unique identifier for the topic.

### Request Example
```
curl -X PUT https://app.useomnia.com/api/v1/topics/your_topic_id/toggle-monitoring \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - The updated status of the topic monitoring.
- **data.id** (string) - The unique identifier for the topic.
- **data.isMonitored** (boolean) - The new monitoring status (true if now monitored, false if no longer monitored).

#### Response Example
```json
{
  "data": {
    "id": "topic_1",
    "isMonitored": true
  }
}
```
```

--------------------------------

### POST /api/v1/brands/{brand}/trends

Source: https://docs.useomnia.com/api/index

Creates new trends from a list of imported keywords. This method is asynchronous and requires querying for new trends to see when the import finishes.

```APIDOC
## POST /api/v1/brands/{brand}/trends

### Description
Creates new trends from a list of imported keywords. This method is asynchronous and it requires querying for new trends to see when the import finishes.

### Method
POST

### Endpoint
/api/v1/brands/{brand}/trends

### Parameters
#### Path Parameters
- **brand** (string) - Required - Unique identifier for the brand

#### Query Parameters
None

#### Request Body
- **country** (string) - Required - ISO 3166-1 alpha-2 country code for the topic's target market
- **keywords** (string) - Required - A list of comma-separated keywords to import and use as trends

### Request Example
```json
{
  "country": "us",
  "keywords": "software,tooling,tech"
}
```

### Response
#### Success Response (201)
- **data** (object) - Contains information about the import results.
  - **imported** (integer) - The number of trends successfully imported.
  - **skipped** (integer) - The number of trends skipped during import.

#### Response Example
```json
{
  "data": {
    "imported": 7,
    "skipped": 2
  }
}
```
```

--------------------------------

### Response Structure

Source: https://docs.useomnia.com/api/index

Details on the consistent structure for all API responses, including success and error formats.

```APIDOC
## Responses

We have defined a consistent structure for all API responses.

## Success
Successful responses wrap the result in a `data` field:

```json
{
  "data": {
    "id": "brand_abc123",
    "name": "My Brand"
  }
}
```

## Errors
Failed requests return an `error` object with a numeric code (for your scripts to handle) and a human-readable description: 

```json
{
  "error": {
    "code": 1002,
    "description": "Invalid input parameters"
  }
}
```
```