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.

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.

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.