Generate AI response

Overview

Synchronously calls the ReviewData AI provider to draft a reply for a review, then saves the generated response. It counts 1 unit against the store's ai_response plan quota: hard-stop plans return 403 once exhausted, and soft-stop plans bill the call as overage.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/account/generate-ai-response

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• The target store_id/review_id must sit inside your own account tree. The store (and the review's store) must resolve to a company that is the authenticated user's own person.company_id or a descendant of it.

• Partner (bundle_id=1) and Account (bundle_id=3) roles use the same endpoint. Only the reachable part of the account tree differs.

Quota limit

• Calls are subject to the store's ai_response plan quota. Hard-stop plans return 403 once exhausted; soft-stop plans bill the call as overage.

Request body

• Body:

The controller also pulls review_text and rating from the resolved review itself — they are not client-supplied.

{
  "store_id": 123,
  "review_id": 123,
  "tone": "professional",
  "style": "Short and friendly",
  "owner_instructions": "Mention our support team"
}

Response

• data.success (boolean) — always true on the happy path.
• data.data.response_text (string) — the generated reply text.
• data.data.model (string) — model id used, e.g. gpt-4o-mini.
• data.data.tokens (object) — { input, output, total } token counts (integers).
• data.data.task_id (string) — ReviewData task id.
• data.data.foreign_key (string) — the ReviewData reference id for this response.
• data.data.ai_review_response_id (integer) — id of the persisted AiReviewResponse row.
• data.data.remaining (integer|null) — remaining quota, null when uncapped.
• data.data.overage (boolean) — whether this call was billed as overage.
• data.data.usage_log_id (integer) — usage record id.

Failures: 403 quota exceeded / feature disabled, 422 validation, 502 provider unreachable; review-not-found returns an error envelope.

200 Success · 200

{
  "data": {
    "success": true,
    "data": {
      "ai_review_response_id": 901,
      "response_text": "Thanks for your honest feedback. I am sorry the visit did not meet expectations - please reach out to our support team and we would love to make it right.",
      "model": "gpt-4o-mini",
      "tokens": {
        "input": 412,
        "output": 87,
        "total": 499
      },
      "task_id": "task_a1b2c3",
      "foreign_key": "rd-fk-xyz789",
      "remaining": 47,
      "overage": false,
      "usage_log_id": 5123
    }
  }
}

403 Quota exceeded (hard-stop plan) · 403

{
  "message": "AI response not allowed for this store.",
  "status": "error",
  "errors": {
    "remaining": 0
  }
}

502 Upstream AI provider unreachable · 502

{
  "message": "AI response provider is currently unreachable.",
  "status": "error",
  "errors": []
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/generate-ai-response" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 123, "review_id": 123, "tone": "professional", "style": "Short and friendly", "owner_instructions": "Mention our support team"}'