{"openapi":"3.1.0","info":{"title":"Parlata API","version":"1.0.0","summary":"Read-only API for Parlata voice reviews and customer Q&A on Shopify.","description":"Parlata is a platform for capturing, verifying, and distributing authentic human voice for commerce. This API exposes a merchant's approved voice and text reviews, plus public customer Q&A, for use in custom storefronts, headless setups, AI shopping agents, and BI/analytics tools.\n\nAuthentication is via a merchant-issued API key (Bearer token), available on the Growth plan from Settings → API access.","contact":{"name":"Parlata support","email":"onboarding@parlata.ai","url":"https://parlata.ai"},"license":{"name":"Commercial — Parlata Terms of Service","url":"https://parlata.ai/terms"}},"servers":[{"url":"https://app.parlata.ai/api/v1","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"parlata_xxxxxxxx...","description":"Merchant API key. Generate one in Shopify Admin → Apps → Parlata → Settings → API access (Growth plan and up)."}},"schemas":{"Review":{"type":"object","properties":{"id":{"type":"string","description":"Stable review identifier."},"kind":{"type":"string","enum":["REVIEW","QUESTION"],"description":"REVIEW = product review. QUESTION = answer to a merchant survey question."},"product_id":{"type":"string","nullable":true,"description":"Shopify product GID (gid://shopify/Product/123). Null on orphan reviews submitted via the test flow without a product."},"order_id":{"type":"string","nullable":true,"description":"Shopify order GID this review is tied to."},"stars":{"type":"integer","nullable":true,"minimum":1,"maximum":5,"description":"1-5 rating. Null when neither the customer picked stars nor the AI sentiment classifier produced one."},"language":{"type":"string","enum":["en","es"]},"transcript":{"type":"string","nullable":true,"description":"AI-cleaned text. Safe to render on the storefront."},"raw_transcript":{"type":"string","nullable":true,"description":"Whisper output before GPT cleanup. Use only for analytics; not safe for direct display."},"audio_url":{"type":"string","nullable":true,"format":"uri","description":"1-hour signed URL to the audio file. Re-fetch the review to refresh; cached URLs expire."},"audio_mime_type":{"type":"string","nullable":true,"example":"audio/webm"},"status":{"type":"string","enum":["PENDING_APPROVAL","APPROVED","REJECTED","PUBLISHED"]},"approved_at":{"type":"string","format":"date-time","nullable":true},"rejected_at":{"type":"string","format":"date-time","nullable":true},"rejection_reason":{"type":"string","nullable":true},"merchant_reply":{"type":"string","nullable":true,"description":"Public reply from the merchant, rendered below the review on the PDP."},"merchant_replied_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"verification":{"$ref":"#/components/schemas/Verification"},"survey_prompt":{"type":"object","nullable":true,"description":"Set on QUESTION-kind rows — the prompt the customer was answering, in both languages.","properties":{"en":{"type":"string"},"es":{"type":"string"}}}}},"Verification":{"type":"object","description":"Authenticity check on the voice review. Today: confirms the customer reached the recorder via the signed post-fulfillment link tied to their Shopify order, plus audio metadata sanity. The public 'Verified customer voice' badge on the storefront block renders only when status is VERIFIED. ML voice-humanness detection and cryptographic order proofs are on the roadmap.","properties":{"status":{"type":"string","enum":["PROCESSING","VERIFIED","FLAGGED","FAILED","NOT_APPLICABLE"],"description":"PROCESSING = detector pending. VERIFIED = passed. FLAGGED = anomaly (merchant approval still possible). FAILED = detector errored. NOT_APPLICABLE = text review or imported review (no audio to score)."},"score":{"type":"number","nullable":true,"minimum":0,"maximum":1,"description":"Authenticity score 0..1, where 1 = high confidence human."},"verified_at":{"type":"string","format":"date-time","nullable":true}},"required":["status"]},"Question":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"asker_name":{"type":"string","nullable":true},"asker_email":{"type":"string","nullable":true},"language":{"type":"string","enum":["en","es"]},"transcript":{"type":"string","nullable":true},"audio_url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","ANSWERED","REJECTED"]},"created_at":{"type":"string","format":"date-time"},"answer":{"type":"object","nullable":true,"properties":{"text":{"type":"string","nullable":true},"audio_url":{"type":"string","format":"uri","nullable":true},"answered_by":{"type":"string","nullable":true},"is_ai_generated":{"type":"boolean"},"published_at":{"type":"string","format":"date-time","nullable":true}}}}},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":"string","nullable":true,"description":"Pass back as ?cursor= on the next request, or null when no more rows remain."}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine-readable error code: invalid_api_key, plan_required, rate_limited, server_error."}}}}},"security":[{"bearerAuth":[]}],"paths":{"/reviews":{"get":{"summary":"List reviews","description":"Returns voice and text reviews for the authenticated merchant. Defaults to APPROVED reviews ordered by most recent. Supports filtering by status, kind (review vs survey), and product, plus cursor-based pagination.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","published","rejected","all"],"default":"approved"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["review","survey"]}},{"name":"product_id","in":"query","description":"Shopify product GID or numeric id.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Review id from a previous next_cursor."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include API access. Upgrade to Growth.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/qa":{"get":{"summary":"List public Customer Q&A","description":"Returns visitor-asked product questions and the merchant's answers, scoped to the authenticated merchant.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","answered","rejected","all"],"default":"answered"}},{"name":"product_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}}}}}}}}}