api-reference

1. Crie um token API ou uma chave de website

Crie um token API de workspace na página API Tokens quando precisar de acesso programático a todos os websites do workspace, incluindo integrações MCP e OpenClaw. Tokens de workspace usam o prefixo flow_ws_. Para tracking server-to-server de um único website, crie uma chave API de website em Settings > API desse website; chaves de website usam o prefixo flow_. Copie novos tokens imediatamente porque o segredo só aparece uma vez.

2. Autenticar suas requisições

Cada chamada API deve incluir o header Authorization usando o esquema Bearer. Use um token de workspace flow_ws_ para acesso API multi-website, ou uma chave de website flow_ para um único website.

Cabeçalho de autorização
Authorization: Bearer YOUR_API_KEY

3. Começar a fazer requisições

A URL base para todos os endpoints v1 é: https://analytics.flowsery.com/analytics/api/v1/. Com um token de workspace, chame GET /websites primeiro e depois passe websiteId ou domain nas solicitações. Chaves de website já são limitadas a um website e não precisam de seletor.

Escolher um workspace

Cada chamada roda em um workspace. Sem o cabeçalho opcional X-Workspace-Id, ela cai no seu workspace padrão. Um login OAuth, como o conector do Claude ou do ChatGPT, pode alcançar todos os workspaces de que o membro faz parte, em todas as organizações: chame GET /workspaces para listá-los e envie o id desejado em X-Workspace-Id em cada requisição. Uma chave API pertence a um workspace, então envie o próprio id dela ou omita o cabeçalho.

Cabeçalho de workspace
X-Workspace-Id: cm8ws1a2b3

Um workspace que o chamador não pode alcançar responde 403 Forbidden com o código workspace_access_denied. Uma chave API ou chave de website enviada com o id de outro workspace recebe o mesmo erro.

Erro de acesso ao workspace
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "cm8ws4c5d6",
  "message": "Você não tem acesso ao espaço de trabalho cm8ws4c5d6. Chame GET /workspaces para listar os espaços de trabalho que pode usar e envie um desses ids no cabeçalho X-Workspace-Id."
}

Formato de resposta

Respostas bem-sucedidas retornam um status 200 OK com um corpo estruturado como:

Resposta bem-sucedida
{
  "status": "success",
  "data": { ... }
}

Os erros usam o formato normal de resposta de erros HTTP NestJS.

Resposta de erro
{
  "message": "Unauthorized",
  "statusCode": 401
}

Códigos de erro padrão

<strong>400 Bad Request</strong> -- A entrada é inválida ou faltam parâmetros obrigatórios, por exemplo um token de workspace sem websiteId ou domain. Uma chave de site que chama GET /workspaces também recebe 400.<br /><strong>401 Unauthorized</strong> -- O token API está ausente, é inválido ou foi revogado. O código token_issuer_lost_access significa que o membro que criou a chave perdeu o acesso ao workspace; crie uma chave nova.<br /><strong>403 Forbidden</strong> -- workspace_access_denied: o cabeçalho X-Workspace-Id indica um workspace que esta credencial não alcança. subscription_required: o plano não inclui mais acesso à API. permission_denied: seu papel no workspace não tem a permissão flowsery.write, que Admins e Editors têm. No teste grátis, problemas detectados pela IA além dos 10 primeiros retornam "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- O recurso solicitado não existe.<br /><strong>429 Too Many Requests</strong> -- Mais de 600 requisições em um minuto para esta chave. Aguarde os segundos indicados em Retry-After. Toda resposta traz RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.<br /><strong>500 Internal Server Error</strong> -- Ocorreu um problema inesperado no servidor.
Exemplo de requisição (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"
    }
  ]
}