Skip to main content

API conventions

These rules apply across every endpoint. They are documented once here and referenced throughout.

Base URL and versioning​

All paths live under https://api.brandindex.com/v1. The /v1 segment is the API version.

GET and POST​

Endpoints use GET or POST. Note that POST endpoints do not create resources on the server — a slight divergence from standard REST. POST is used simply because the request needs a body: for example, /v1/analyses/execute carries an analysis definition, and GET requests cannot have a body.

The request/response envelope​

JSON request bodies and successful JSON responses use a consistent envelope:

{
  "meta": { "version": "v1" },
  "data": { }
}
  • meta.version — currently always "v1".
  • data — the resource-specific payload.

Two kinds of response are not enveloped: error responses, which are a flat { "message", "error_code", "request_id", "extra" } object (see the error-code reference), and CSV/file responses, whose body is the file content itself.

Content types​

  • JSON is the default for request and response bodies.
  • CSV — append .csv to an execute path (e.g. POST /v1/analyses/execute.csv) to get a flat CSV response instead of JSON.
  • File downloads — the export endpoints return a file (Excel or CSV) with a Content-Disposition filename.

Listing endpoints​

List endpoints (e.g. GET /v1/analyses) commonly accept an is_listed query parameter to filter to listed resources. Archived resources are excluded by default.

Errors​

Errors use standard HTTP status codes with a JSON body describing the problem. The ones you are most likely to meet:

StatusMeaning
400Invalid input, or a request that asks for too much data.
401Not authenticated — missing or invalid credentials on a protected endpoint.
403Authenticated but not entitled to the resource.
429Rate or volume limit exceeded — wait and retry.

A failed POST /v1/auth/login (wrong password or unknown email) returns 404, not 401 — see Authentication.

See the error-code reference for the full list.

Rate and volume limits​

Requests are limited both per request (how much data one call may ask for) and over time (how many calls / how much data in a window). Exceeding the per-request ceiling returns 400; exceeding the time-window limits returns 429. See Request size & limits.

Caching​

Identical requests may be served from a short-lived cache, so repeated calls can return quickly without recomputation.