api-reference

1. Utwórz token API lub klucz witryny

Token API obszaru roboczego tworzy się na stronie Tokeny API, gdy potrzebny jest programowy dostęp do wszystkich witryn w obszarze roboczym, w tym integracje MCP i OpenClaw. Tokeny obszaru roboczego mają prefiks flow_ws_. Do śledzenia serwer-serwer jednej witryny służy klucz API witryny ze strony Ustawienia > API tej witryny; klucze witryn mają prefiks flow_. Nowe tokeny należy skopiować od razu, ponieważ sekret jest pokazywany tylko raz.

2. Uwierzytelnij żądania

Każde wywołanie API musi zawierać nagłówek Authorization w schemacie Bearer. Do dostępu do wielu witryn służy token obszaru roboczego flow_ws_, a do jednej witryny klucz witryny flow_.

Nagłówek Authorization
Authorization: Bearer YOUR_API_KEY

3. Zacznij wysyłać żądania

Bazowy adres URL wszystkich punktów końcowych v1 to: https://analytics.flowsery.com/analytics/api/v1/. Z tokenem obszaru roboczego należy najpierw wywołać GET /websites, a potem przekazywać websiteId lub domain w żądaniach. Klucze witryn są już przypisane do jednej witryny i nie wymagają wskazania.

Wybór obszaru roboczego

Każde wywołanie działa w jednym obszarze roboczym. Bez opcjonalnego nagłówka X-Workspace-Id trafia do domyślnego obszaru. Logowanie OAuth, np. przez konektor Claude lub ChatGPT, daje dostęp do wszystkich obszarów roboczych członka, także w różnych organizacjach: GET /workspaces zwraca ich listę, a wybrany identyfikator wysyła się w X-Workspace-Id przy każdym żądaniu. Klucz API należy do jednego obszaru roboczego, więc należy wysłać jego identyfikator albo pominąć nagłówek.

Nagłówek obszaru roboczego
X-Workspace-Id: cm8ws1a2b3

Obszar roboczy niedostępny dla wywołującego zwraca 403 Forbidden z kodem workspace_access_denied. Ten sam błąd otrzyma klucz API lub klucz witryny wysłany z identyfikatorem innego obszaru.

Błąd dostępu do obszaru roboczego
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "cm8ws4c5d6",
  "message": "Brak dostępu do obszaru roboczego cm8ws4c5d6. GET /workspaces zwraca listę dostępnych obszarów; jeden z ich identyfikatorów należy wysłać w nagłówku X-Workspace-Id."
}

Format odpowiedzi

Udane odpowiedzi zwracają status 200 OK i treść o następującej strukturze:

Odpowiedź po sukcesie
{
  "status": "success",
  "data": { ... }
}

Błędy mają standardowy format odpowiedzi HTTP NestJS.

Odpowiedź z błędem
{
  "message": "Unauthorized",
  "statusCode": 401
}

Standardowe kody błędów

<strong>400 Bad Request</strong> -- Dane wejściowe są nieprawidłowe lub brakuje wymaganych parametrów, np. token obszaru roboczego bez websiteId lub domain. Klucz witryny wywołujący GET /workspaces także otrzymuje 400.<br /><strong>401 Unauthorized</strong> -- Token API jest nieobecny, nieprawidłowy lub unieważniony. Kod token_issuer_lost_access oznacza, że członek, który utworzył klucz, stracił dostęp do obszaru roboczego; należy utworzyć nowy klucz.<br /><strong>403 Forbidden</strong> -- workspace_access_denied: nagłówek X-Workspace-Id wskazuje obszar roboczy niedostępny dla tych danych uwierzytelniających. subscription_required: plan nie obejmuje już dostępu do API. permission_denied: rola w obszarze roboczym nie ma uprawnienia flowsery.write, które mają Administratorzy i Edytorzy. W okresie próbnym problemy wykryte przez AI poza pierwszymi 10 zwracają "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- Żądany zasób nie istnieje.<br /><strong>429 Too Many Requests</strong> -- Ponad 600 żądań na minutę dla tego klucza. Należy odczekać liczbę sekund podaną w Retry-After. Każda odpowiedź zawiera RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset.<br /><strong>500 Internal Server Error</strong> -- Na serwerze wystąpił nieoczekiwany problem.
Przykładowe żądanie (Curl)
curl --request GET \
  --url https://analytics.flowsery.com/analytics/api/v1/websites \
  --header 'Authorization: Bearer <workspace-api-token>'
200
{
  "status": "success",
  "data": [
    {
      "id": "cm8abc123",
      "domain": "example.com",
      "timezone": "America/New_York",
      "currency": "USD",
      "trackingId": "flid_abc123"
    }
  ]
}