Using the API

The complete, always-current endpoint reference is generated from the API itself:

api.evidentugc.com/docs

That is the authority for paths, parameters and response shapes. This page covers the conventions behind it — the things that are true everywhere and are not repeated on every endpoint.

Base URL and version

https://api.evidentugc.com/api/v1

Authentication

A bearer token plus the store environment:

curl https://api.evidentugc.com/api/v1/reviews \
  -H "Authorization: Bearer evnt_YOUR_API_KEY" \
  -H "x-store-env-id: YOUR_STORE_ENV_ID"

Both headers are required on essentially everything. See API keys & scopes.

Tenancy is not optional

Every query is scoped to a store environment, and the API refuses queries that do not name one. This is enforced at the data layer rather than left to each endpoint to remember, so there is no endpoint that quietly returns everything if you omit the header.

The practical consequence: if you manage several stores, you make one call per store. There is no cross-store query.

Upserts, and what “replace” means

The bulk write endpoints — PUT /products, PUT /orders — are upserts keyed on your identifiers (platformProductId, platformOrderId). Re-sending the same payload is safe and idempotent.

They replace rather than merge. A field you omit is cleared, not left alone. Always send the whole object.

Up to 250 items per call. Items are independent: one bad row does not fail the batch, so check the failed count in the response body rather than trusting a 200.

Errors

Errors return a JSON body with a message and, where the reason is actionable, a code. Read the code rather than pattern-matching the message.

The billing gates are the ones worth handling explicitly:

Code	Meaning
plan_required	The feature needs a higher plan
subscription_expired	The subscription has lapsed

Both arrive as 403. Without reading the code you cannot tell them apart from an ordinary permission failure, and you will show your user the wrong thing.

Rate limits

10 per second, 50 per ten seconds, 200 per minute, per caller. Batch rather than loop. A 429 means back off — retry with exponential backoff rather than immediately.

Storefront write limits

The endpoints shoppers write to from your storefront are much tighter, because they are unauthenticated and counted per visitor IP rather than per key. If you are building your own review form, these are the numbers you will hit first:

Endpoint	Per second	Per minute
Review submission (POST /reviews)	3	5
Video upload URL for the review form	1	3
Gallery photo submission	3	10
Gallery lead form	3	10
Gallery favourite	5	30
Helpful vote (POST /reviews/:id/helpful)	5	20
Image upload (POST /uploads/image)	5	20

Five reviews a minute from one IP is plenty for real shoppers and is the limit you will meet when testing a form by hand. Wait a minute rather than assuming the form is broken.

Pagination

List endpoints paginate. Follow the pagination fields in the response rather than assuming a page size; ask for what you need rather than walking the whole collection to filter client-side.

There are two shapes, and a helper written for one will not work on the other:

• Page-numbered — almost every list endpoint. The response is { "data": [...], "meta": { "total", "page", "limit", "totalPages" } }; ask for the next page until you reach totalPages.
• Cursor — the webhook event log (GET /outbound-webhooks/events). The response is { "events": [...], "next_cursor" }; pass next_cursor back as since until it comes back null. A time-ordered stream that is still being written to cannot use page numbers without skipping or repeating rows as new events land, which is why this one is different.

Dates

ISO 8601, UTC, everywhere — in and out.

Webhooks out

To be told when something changes rather than polling for it, register an outbound webhook.

Agents

If what you are building is an AI assistant rather than a service, the MCP server wraps this API with the same keys and the same permissions, and saves you writing the client.