Prisma Reviews Usage API

openapi: 3.2.0
info:
  title: Prisma Reviews Usage API
  version: 1.0.0
  summary: One REST API to read and reply to reviews on the App Store, Google Play, Yelp, Tripadvisor and more.
  description: 'Read the reviews of the businesses and apps you own or manage on the App Store, Google Play, Judge.me, eBay, Trusted Shops, eKomi, Yelp, Tripadvisor, Booking.com, G2 and 50+ more platforms, all in one normalized JSON shape, and reply through each platform''s official API where it has one (read-only platforms return the link where a review is answered). Google Business Profile, Trustpilot, Allegro, Etsy, Angi and Mercado Libre are coming soon: `GET /v1/platforms` says which platforms are ready (`live_ready`).


    - **Auth:** `Authorization: Bearer `. Live keys (`pk_live_…`) work with real accounts; test keys (`pk_test_…`) connect any platform with sample locations and reviews and never publish replies. Test and live data never mix.

    - **Format:** JSON in and out; timestamps are ISO 8601 in UTC; IDs are prefixed (`rev_`, `loc_`, `con_`, `we_`, `evt_`, `req_`).

    - **Pagination:** `GET /v1/reviews` is cursor paginated (`data` + `next_cursor`).

    - **Rate limits:** per key and per minute, set by the plan (Spark 60, Beam 120, Spectrum 600, Aurora 1,200), reported in `X-RateLimit-Limit` and `X-RateLimit-Remaining`.

    - **Errors:** one shape, `{ "error": { "type", "code", "message", "retryable", "request_id", "docs_url" } }`; codes on https://prismareviews.com/docs/errors.

    - **Webhooks:** signed `POST`s for new and updated reviews, published or failed replies and connection changes.


    Get a free API key at https://app.prismareviews.com/signup.'
  termsOfService: https://prismareviews.com/terms
  contact:
    name: Prisma Reviews
    url: https://prismareviews.com
    email: hello@prismareviews.com
  x-logo:
    url: https://prismareviews.com/favicon.svg
    altText: Prisma Reviews
servers:
- url: https://api.prismareviews.com
  description: Production (live and test keys)
security:
- apiKey: []
tags:
- name: Usage
  description: Your plan and this month's usage.
  externalDocs:
    description: Docs
    url: https://prismareviews.com/docs/api-reference/usage
paths:
  /v1/usage:
    get:
      operationId: getUsage
      tags:
      - Usage
      summary: Get usage
      description: The workspace's plan and what it has used in the current calendar month (UTC). The same numbers with a live key and a test key.
      responses:
        '200':
          description: Usage this month.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
              example:
                plan: beam
                period: 2026-10
                locations:
                  used: 7
                  limit: 10
                requests: 18234
                requests_per_minute_limit: 120
                replies_published: 412
                paid_reads:
                  used: 640
                  limit: 2500
                  free_trial:
                    status: not_applicable
                    reads: 100
                    used: 0
                    left: 100
                    platforms:
                    - google_maps
                    - tripadvisor
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Maintenance'
      externalDocs:
        description: Docs
        url: https://prismareviews.com/docs/api-reference/usage
components:
  responses:
    InternalError:
      description: Something failed on Prisma's side. Retryable.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal_error:
              value:
                error:
                  type: api_error
                  code: internal_error
                  message: Something went wrong on our side. It has been logged; try again.
                  retryable: true
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#internal_error
    RateLimited:
      description: More requests this minute than the plan allows for this key. Not counted in usage.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rate_limited:
              value:
                error:
                  type: rate_limit_error
                  code: rate_limited
                  message: Rate limit of 60 requests per minute exceeded. Retry in 12 s. Requests over the limit are never billed.
                  retryable: true
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#rate_limited
    Unauthorized:
      description: No API key or one not shaped like a Prisma key (`missing_api_key`), or a key that doesn't exist or was revoked (`invalid_api_key`).
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_api_key:
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: 'Send your API key as "Authorization: Bearer pk_live_…".'
                  retryable: false
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#missing_api_key
            invalid_api_key:
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: This API key does not exist or was revoked.
                  retryable: false
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#invalid_api_key
    Forbidden:
      description: The account is suspended.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            account_suspended:
              value:
                error:
                  type: permission_error
                  code: account_suspended
                  message: This account is suspended. Write to hello@prismareviews.com.
                  retryable: false
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#account_suspended
    Maintenance:
      description: Prisma is under maintenance and the API is paused. Retryable.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            maintenance:
              value:
                error:
                  type: api_error
                  code: maintenance
                  message: Prisma is under maintenance. Try again in a few minutes; see https://prismareviews.com/status.
                  retryable: true
                  request_id: req_01KJ8T3C5D7E9F1G3H5J7K9M1N
                  docs_url: https://prismareviews.com/docs/errors#maintenance
  headers:
    X-RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
    Request-Id:
      description: The `req_…` ID of the request. Include it when you contact support.
      schema:
        type: string
    X-RateLimit-Limit:
      description: Requests allowed per minute for this key.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - error
      description: Every error has this shape. Some codes add fields (for example `platform`, `url`, `max_length`, `connection_id`, `upgrade_url`, `required_fields`).
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - retryable
          - request_id
          - docs_url
          additionalProperties: true
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - not_found_error
              - conflict_error
              - invalid_request_error
              - rate_limit_error
              - api_error
              description: Family of the error, from the HTTP status.
            code:
              type: string
              description: Stable, machine-readable code. Branch on this, not on `message`.
            message:
              type: string
              description: Human-readable explanation. It can change.
            retryable:
              type: boolean
              description: '`true` for 429 and 5xx: the same request can succeed later.'
            request_id:
              type: string
              description: The `req_…` ID, also in the `Request-Id` header.
            docs_url:
              type: string
              description: Description of this code.
              format: uri
    Usage:
      type: object
      required:
      - plan
      - period
      - locations
      - requests
      - requests_per_minute_limit
      - replies_published
      - paid_reads
      properties:
        plan:
          type: string
          enum:
          - spark
          - beam
          - spectrum
          - aurora
          - custom
        period:
          type: string
          description: The current month, `YYYY-MM` in UTC.
          pattern: ^\d{4}-\d{2}$
        locations:
          type: object
          required:
          - used
          - limit
          properties:
            used:
              type: integer
              description: Active live locations (test and disconnected ones are not counted).
            limit:
              type: integer
              description: Locations of your plan plus the extra locations you pay for.
        requests:
          type: integer
          description: API requests this month from all of the workspace's keys, test keys included. Requests over the rate limit are not counted.
        requests_per_minute_limit:
          type: integer
          description: Your per-key rate limit.
        replies_published:
          type: integer
          description: Replies published through Prisma this month.
        paid_reads:
          type: object
          required:
          - used
          - limit
          properties:
            used:
              type: integer
              description: Reads used this month by platforms read through paid data providers (Yelp, Tripadvisor, Booking.com…) on live connections.
            limit:
              type: integer
              description: 'Reads included this month: the plan''s plus read packs.'
            free_trial:
              type: object
              description: One-off free reads (100 per account, never renewed) to try Google Maps and Tripadvisor with real data.
              properties:
                status:
                  type: string
                  enum:
                  - available
                  - active
                  - used_up
                  - verify_email
                  - not_applicable
                  description: '`verify_email`: verify the account email first. `not_applicable`: the workspace has paid reads of its own, used instead.'
                reads:
                  type: integer
                used:
                  type: integer
                left:
                  type: integer
                platforms:
                  type: array
                  items:
                    type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: pk_live_… / pk_test_…
      description: 'Your secret API key as a Bearer token: `pk_live_…` for real accounts, `pk_test_…` for sample data. Keep it on your server.'
externalDocs:
  description: Prisma Reviews API reference
  url: https://prismareviews.com/docs/api-reference