Errors

# -i prints the status line and the headers, including X-Request-Id.
# Set ORG_ID and BRAND_ID to ids your key can reach.
curl -i -G "https://api.surfais.com/v1/orgs/$ORG_ID/brands/$BRAND_ID/scores" \
  --data-urlencode "from=2026-09-10" \
  --data-urlencode "to=2026-09-01" \
  -H "Authorization: Bearer $SURFAIS_API_KEY"

import os

import requests

BASE_URL = "https://api.surfais.com/v1"
API_KEY = os.environ["SURFAIS_API_KEY"]
ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60"


class SurfaisApiError(Exception):
    """An error envelope: the status, the stable code, its details and the request id."""

    def __init__(self, response):
        body = response.json()
        self.status = response.status_code
        self.code = body["error"]["code"]
        self.details = body["error"].get("details")
        self.request_id = body["request_id"]
        super().__init__(
            f'{self.status} {self.code}: {body["error"]["message"]} '
            f"(request {self.request_id})"
        )


def get(path, params=None):
    response = requests.get(
        f"{BASE_URL}{path}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
        timeout=30,
    )
    if not response.ok:
        raise SurfaisApiError(response)
    return response.json()


try:
    scores = get(
        f"/orgs/{ORG_ID}/brands/{BRAND_ID}/scores",
        {"from": "2026-09-10", "to": "2026-09-01"},  # from is after to
    )
    print(len(scores["data"]), "points")
except SurfaisApiError as error:
    if error.code == "validation_error":
        for problem in error.details:
            print(f'{problem["path"]}: {problem["code"]} ({problem["message"]})')
    elif error.code == "not_found":
        print(f"This key cannot reach that brand (request {error.request_id})")
    else:
        raise

// Node 18+. Save as read-scores.mjs and run: node read-scores.mjs
const BASE_URL = "https://api.surfais.com/v1";
const API_KEY = process.env.SURFAIS_API_KEY;
const ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11";
const BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60";

// An error envelope: the status, the stable code, its details and the request id.
class SurfaisApiError extends Error {
  constructor(status, body) {
    super(`${status} ${body.error.code}: ${body.error.message} (request ${body.request_id})`);
    this.status = status;
    this.code = body.error.code;
    this.details = body.error.details;
    this.requestId = body.request_id;
  }
}

async function get(path, params = {}) {
  const response = await fetch(`${BASE_URL}${path}?${new URLSearchParams(params)}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const body = await response.json();
  if (!response.ok) throw new SurfaisApiError(response.status, body);
  return body;
}

try {
  const scores = await get(`/orgs/${ORG_ID}/brands/${BRAND_ID}/scores`, {
    from: "2026-09-10", // from is after to
    to: "2026-09-01",
  });
  console.log(scores.data.length, "points");
} catch (error) {
  if (!(error instanceof SurfaisApiError)) throw error;
  if (error.code === "validation_error") {
    for (const problem of error.details) {
      console.log(`${problem.path}: ${problem.code} (${problem.message})`);
    }
  } else if (error.code === "not_found") {
    console.log(`This key cannot reach that brand (request ${error.requestId})`);
  } else {
    throw error;
  }
}