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

# POST /simulate-review — Generate a Nigerian review

> Generate an authentic Nigerian restaurant review with a star rating, review text, and tone label by supplying a user persona and restaurant features.

The `/simulate-review` endpoint takes a user persona and a set of restaurant features, then returns a contextually authentic Nigerian restaurant review. The persona drives the reviewer's tone, price sensitivity, and rating tendency, while the features shape what the review focuses on. Most integrations supply a `persona` object directly; the `user_id` field is an alternative that resolves a persona from the built-in review dataset.

## Request

```text theme={null}
POST https://naijataste-api-vcp4.onrender.com/simulate-review
```

You must provide either `user_id` or `persona` — not both, not neither. The API returns `422` if neither field is present.

### Body

<ParamField body="user_id" type="string">
  An ID from the built-in review dataset. The API resolves the full persona automatically. Use this or `persona`, not both. Most integrations should use `persona` directly.
</ParamField>

<ParamField body="persona" type="object">
  A persona object supplied directly. Use this or `user_id`, not both.

  <Expandable title="persona properties">
    <ParamField body="user_id" type="string">
      An optional identifier for this persona, used for traceability.
    </ParamField>

    <ParamField body="avg_rating" type="number">
      The reviewer's historical average star rating (e.g. `3.2`).
    </ParamField>

    <ParamField body="rating_tendency" type="string">
      How the reviewer typically skews their ratings. One of `"harsh"`, `"balanced"`, or `"generous"`.
    </ParamField>

    <ParamField body="price_sensitivity" type="string">
      How strongly the reviewer reacts to price. One of `"high"`, `"medium"`, or `"low"`.
    </ParamField>

    <ParamField body="tone_keywords" type="string[]">
      A list of topics this reviewer commonly mentions, such as `["jollof", "service", "price", "portion"]`.
    </ParamField>

    <ParamField body="total_reviews" type="number">
      The total number of reviews this persona has written.
    </ParamField>

    <ParamField body="sample_reviews" type="string[]">
      One or more example reviews written by this persona, used to calibrate writing style.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="item_name" type="string" required>
  The name of the restaurant or food item being reviewed (e.g. `"Yellow Chilli Victoria Island"`).
</ParamField>

<ParamField body="item_type" type="string" required>
  The type of item. Typically `"restaurant"`.
</ParamField>

<ParamField body="location" type="string" required>
  The city or area where the restaurant is located (e.g. `"Lagos"`).
</ParamField>

<ParamField body="features" type="string[]" required>
  A list of attributes describing the restaurant's experience (e.g. `["expensive", "nice ambience", "average food", "fast service"]`). These shape what the generated review focuses on.
</ParamField>

## Response

<ResponseField name="rating" type="number" required>
  An integer star rating from 1 to 5, consistent with the persona's rating tendency and the provided features.
</ResponseField>

<ResponseField name="review_text" type="string" required>
  The generated review text, written in a tone matching the persona. May include Nigerian Pidgin English phrases.
</ResponseField>

<ResponseField name="tone_label" type="string" required>
  Describes the language style of the generated review. One of `"pidgin-heavy"`, `"mixed"`, `"formal"`, or `"casual"`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://naijataste-api-vcp4.onrender.com/simulate-review \
    --header "Content-Type: application/json" \
    --data '{
      "persona": {
        "user_id": "demo_user",
        "avg_rating": 3.2,
        "rating_tendency": "harsh",
        "price_sensitivity": "high",
        "tone_keywords": ["jollof", "service", "price", "portion"],
        "total_reviews": 45,
        "sample_reviews": ["The food was okay but too expensive for the portion size"]
      },
      "item_name": "Yellow Chilli Victoria Island",
      "item_type": "restaurant",
      "location": "Lagos",
      "features": ["expensive", "nice ambience", "average food", "fast service"]
    }'
  ```

  ```json Response theme={null}
  {
    "rating": 2,
    "review_text": "The ambience correct sha, but for this price? Abeg. Food no reach expectation at all. My wallet dey cry.",
    "tone_label": "pidgin-heavy"
  }
  ```
</CodeGroup>

## Errors

| Status | Cause                                                                                 |
| ------ | ------------------------------------------------------------------------------------- |
| `422`  | Neither `user_id` nor `persona` was provided, or required persona fields are missing. |
| `502`  | The Gemini AI layer returned an unexpected or unparseable response.                   |
| `503`  | The Gemini AI service is unavailable or not configured.                               |