> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.trendhero.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How does the TrendHero API work?

The **trendHero** API is based on REST principles. All requests are made using predictable, resource-oriented URLs, and responses are returned in JSON format. The API uses standard HTTP status codes and supports authentication, ensuring ease of use and integration. With a consistent and reliable interface, interacting with the services becomes intuitive.

```json
https://api.trendhero.io/api/public/v1
```

### Authentication

The **trendHero** API uses an API key for authentication. Keys can be managed on the [Access Tokens](https://trendhero.io/app/api/access-tokens) page.  
All requests must include the API key via bearer authentication. The key should be passed in the request header:

```json
curl ... -H 'Authorization: Bearer access_token'
```

**Important:** Requests without authentication will not be executed.

### Working with Reports

###### Report Statuses

Reports in **trendHero** can be in various statuses depending on their processing stage.

**Ready statuses:**
- `ready` — The report is ready and available.
- `impossibleButReady` — The report is marked as ready despite issues during its creation.

**Collection statuses:**
- `collecting` — The report is in the process of data collection.
- `recollecting` — A retry is in progress to collect data for the report.

**Unavailable statuses:**
- `impossible` — The report cannot be created due to insurmountable limitations.

###### Report Structure

Initially, the report contains only the `preview` key. After purchase, the following keys are available:
- `report` — The main data of the report.
- `openai_report` — The report data generated by OpenAI.
- `saves_shares_report` — Data about shares and saves.

Each of these keys has its status, indicating the processing stage of the corresponding part of the report.

###### Create a Report

This endpoint allows creating a report for a specific user.

```json
curl --location --request POST 'https://api.trendhero.io/api/public/v1/reports?username=davidrobsonyoga' --header 'Authorization: Bearer access_token'
```

**Parameters:**
- Type: string
- Example: `davidrobsonyoga`
- Description: The username for which the report needs to be created.

**Example request:**
```json
POST /api/reports
```

**Response:**
The API's response to the POST request to create a report will contain a JSON object with several nested fields. Each field will contain different subfields with various data types, such as integers, strings, arrays, and nested objects.

If the report status is `collecting`, the system will send you a callback when the report is ready.

###### Show Report

This endpoint allows retrieving a report for a specific user.

**Parameters:**
- Type: string
- Example: `davidrobsonyoga`
- Description: The username for which the report needs to be retrieved.

**Example request:**
```bash
GET /api/reports/{username}
```

**Response:**
The API's response to the GET request to retrieve a report will contain a JSON object with several nested fields. Each field will contain different subfields with various data types, such as integers, strings, arrays, and nested objects.