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 <code>flow_ws_</code>. 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 <code>flow_</code>. Copie novos tokens imediatamente porque o segredo só aparece uma vez.

2. Autenticar suas requisicoes

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

Cabecalho de autorizacao
Authorization: Bearer YOUR_API_KEY

3. Comecar a fazer requisicoes

A URL base para todos os endpoints v1 é: <code>https://analytics.flowsery.com/analytics/api/v1/</code>. Com um token de workspace, chame <code>GET /websites</code> primeiro e depois passe <code>websiteId</code> ou <code>domain</code> 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 <code>X-Workspace-Id</code>, 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 <code>GET /workspaces</code> para listá-los e envie o id desejado em <code>X-Workspace-Id</code> 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 <code>403 Forbidden</code> com o código <code>workspace_access_denied</code>. 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 utilizam o formato normal de resposta de erros HTTP NestJS.

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

Codigos de erro padrao

<strong>400 Bad Request</strong> -- A entrada é inválida ou faltam parâmetros obrigatórios, por exemplo um token de workspace sem <code>websiteId</code> ou <code>domain</code>. Uma chave de site que chama <code>GET /workspaces</code> também recebe 400.<br /><strong>401 Unauthorized</strong> -- O token API está ausente, é inválido ou foi revogado. O código <code>token_issuer_lost_access</code> significa que o membro que criou a chave perdeu o acesso ao workspace; crie uma chave nova.<br /><strong>403 Forbidden</strong> -- <code>workspace_access_denied</code>: o cabeçalho X-Workspace-Id indica um workspace que esta credencial não alcança. <code>subscription_required</code>: o plano não inclui mais acesso à API. <code>permission_denied</code>: seu papel no workspace não tem a permissão <code>flowsery.write</code>, 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 <code>Retry-After</code>. Toda resposta traz <code>RateLimit-Policy</code>, <code>RateLimit-Limit</code>, <code>RateLimit-Remaining</code> e <code>RateLimit-Reset</code>.<br /><strong>500 Internal Server Error</strong> -- Ocorreu um problema inesperado no servidor.
Exemplo de requisicao (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"
    }
  ]
}