# Anecdote API

## Anecdote AI Public API Documentation

This document provides documentation for the Anecdote AI Public API.

### Authentication

All requests to the API must be authenticated using a Bearer token in the `Authorization` header.

`Authorization: Bearer <YOUR_TOKEN>`

A token can be obtained by sending a request to the support team.

### Endpoints

The base URL for all endpoints is `https://public-api.anecdoteai.com`

The following endpoints are available:

* `POST /public/export`
* `POST /public/search`
* `POST /public/trend`
* `POST /public/distribution`
* `POST /public/quantify`
* `POST /public/deeper-search`

***

### Filtering

Many endpoints support a `filters` parameter in the request body. This allows you to narrow down your requests based on specific criteria.

A filter is a JSON object with the following structure:

* `key` (string): The field to filter on.
* `operator` (string): The comparison operator (e.g., `eq`, `neq`).
* `type` (string): The type of filter, such as `range` or `list`.
* `value`/`values`/`min`/`max`: The value(s) to filter by.

#### Filter Examples

**Range Filter**

To filter for entries within a specific date range:

```json
{
    "key": "ds",
    "type": "range",
    "operator": "eq",
    "min": "2025-07-02",
    "max": "2025-07-08"
}
```

**List Filter**

To filter for entries from a specific source:

```json
{
    "key": "source",
    "type": "list",
    "operator": "eq",
    "values": ["App Store"]
}
```

***

#### Export

This endpoint is used to export data.

* **Endpoint:** `POST /public/export`
* **Method:** `POST`

**Request Body**

The request body should be a JSON object with the following fields:

* `export_fields` (list of strings, required): A list of fields to include in the export.
* `emails` (list of strings, optional): A list of email addresses to send the export to.
* `filters` (list of objects, optional): A list of filters to apply to the data.

**Example Request**

```bash
curl -X POST 'https://public-api.anecdoteai.com/public/export' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "export_fields": [
        "ds",
        "sentiment__filter",
        "source name__filter",
        "anecdote_ids",
        "category_ids",
        "custom_url",
        "source"
    ],
    "emails": [],
    "filters": [
        {
            "key": "ds",
            "type": "range",
            "operator": "eq",
            "min": "2025-06-24",
            "max": "2025-06-28"
        }
    ]
}'
```

***

#### Search

This endpoint performs a search operation.

* **Endpoint:** `POST /public/search`
* **Method:** `POST`

**Request Body**

The request body is a JSON object with the following fields.

* `search_query` (string, optional): The search query.
* `custom_prompt_begin` (string, optional): Text to prepend to the summary prompt.
* `custom_prompt_end` (string, optional): Text to append to the summary prompt.
* `additional_fields` (list of strings, optional): Additional fields to include in the search.
* `filters` (array, optional): Filters to apply to the search.
* `limit` (integer, optional): The maximum number of results to return.
* `offset` (integer, optional): The starting offset for results.
* `sorted_by` (array, optional): A list of sort objects.

**Example Request**

```bash
curl -X POST 'https://public-api.anecdoteai.com/public/search' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "search_query": "calendar",
    "custom_prompt_begin": "",
    "custom_prompt_end": "Summarize the calendar related issues as bullet points",
    "additional_fields": [],
    "filters": [
        {
            "key": "ds",
            "type": "range",
            "operator": "eq",
            "min": "2025-07-02",
            "max": "2025-07-08"
        },
        {
            "key": "source",
            "type": "list",
            "operator": "eq",
            "values": [
                "App Store"
            ]
        }
    ]
}'
```

***

#### Trend

This endpoint retrieves trend data.

* **Endpoint:** `GET /public/trend`
* **Method:** `GET`

**Query Parameters**

* `trend_on` (string, optional): The field to calculate the trend on. Default: `volume`.
* `trend_by` (string, optional): The aggregation period for the trend (e.g., `day`, `week`). Default: `-`.

**Request Body**

A `GET` request to this endpoint can optionally include a JSON body to specify filters.

```json
{
  "query": "search query",
  "filters": [
    {
      "key": "field_name",
      "value": "field_value",
      "operator": "eq"
    }
  ]
}
```

**Example Request**

```bash
curl -X GET 'https://public-api.anecdoteai.com/public/trend?trend_on=volume&trend_by=week' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "performance",
    "filters": [
        {"key": "sentiment", "value": "negative", "operator": "eq"}
    ]
}'
```

***

#### Distribution

This endpoint retrieves distribution data. It can be accessed via `GET` or `POST`.

* **Endpoint:** `/public/distribution`
* **Methods:** `GET`, `POST`

**Query Parameters**

* `distribution_of` (string, optional): Field for which to calculate the distribution. Default: `volume`.
* `distribution_by` (string, optional): Field to group the distribution by. Default: `-`.
* `stacked_by` (string, optional): Field for stacking in the distribution. Default: `-`.

**Request Body (`GET`)**

The `GET` request can optionally contain a body with a search query and filters.

```json
{
  "query": "search query",
  "filters": []
}
```

**Example Request (`GET`)**

```bash
curl -X GET 'https://public-api.anecdoteai.com/public/distribution?distribution_by=tags' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "bugs"
}'
```

**Request Body (`POST`)**

The `POST` request accepts a full search request body, allowing for more complex queries.

```json
{
  "search_query": "your search query",
  "filters": [],
  "limit": 100
}
```

**Example Request (`POST`)**

```bash
curl -X POST 'https://public-api.anecdoteai.com/public/distribution?distribution_by=sentiment' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "search_query": "user feedback"
}'
```

***

#### Quantify

This endpoint is used for quantitative analysis.

* **Endpoint:** `POST /public/quantify`
* **Method:** `POST`

**Request Body**

The request body contains `main_query`, `main_filters`, `secondary_query`, and `secondary_filters`.

```json
{
    "main_query": "main search query",
    "main_filters": [],
    "secondary_query": "secondary search query",
    "secondary_filters": []
}
```

**Example Request**

```bash
curl -X POST 'https://public-api.anecdoteai.com/public/quantify' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "main_query": "users who mentioned billing",
    "secondary_query": "users who churned"
}'
```

***

#### Deeper Search

This endpoint performs a more in-depth, agent-based search.

* **Endpoint:** `POST /public/deeper-search`
* **Method:** `POST`

**Request Body**

The request body is similar to the `Search` endpoint but is designed for more complex, conversational queries that an agent can break down.

```json
{
  "search_query": "a complex question for the search agent",
  "filters": []
}
```

**Example Request**

```bash
curl -X POST 'https://public-api.anecdoteai.com/public/deeper-search' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "search_query": "What are the main reasons users are reporting for account cancellation in the last quarter?"
}'
```