1. Crea un token API o una chiave del sito
Crea un token API del workspace dalla pagina Token API quando ti serve accesso programmatico a tutti i siti del tuo workspace, incluse le integrazioni MCP e OpenClaw. I token del workspace usano il prefisso flow_ws_. Per il tracciamento server-to-server di un solo sito, crea una chiave API del sito dalla pagina Impostazioni > API di quel sito; le chiavi del sito usano il prefisso flow_. Copia subito i nuovi token, perché il segreto viene mostrato una sola volta.
2. Autentica le tue richieste
Ogni chiamata API deve includere l'header Authorization con lo schema Bearer. Usa un token del workspace flow_ws_ per l'accesso API a più siti, oppure una chiave del sito flow_ per un solo sito.
Authorization: Bearer YOUR_API_KEY3. Inizia a fare richieste
L'URL di base per tutti gli endpoint v1 è: https://analytics.flowsery.com/analytics/api/v1/. Con un token del workspace, chiama prima GET /websites, poi passa websiteId o domain alle richieste agli endpoint. Le chiavi del sito sono già limitate a un sito e non richiedono un selettore.
Scegli un workspace
Ogni chiamata viene eseguita in un workspace. Senza l'header facoltativo X-Workspace-Id finisce nel tuo workspace predefinito. Un accesso OAuth, come il connettore di Claude o ChatGPT, raggiunge tutti i workspace a cui appartiene il membro, anche in organizzazioni diverse: chiama GET /workspaces per elencarli, poi invia l'id che ti serve in X-Workspace-Id in ogni richiesta. Una chiave API appartiene a un solo workspace, quindi invia il suo id oppure ometti l'header.
X-Workspace-Id: cm8ws1a2b3Un workspace che il chiamante non può raggiungere risponde 403 Forbidden con il codice workspace_access_denied. Lo stesso errore arriva a una chiave API o a una chiave del sito inviata con l'id di un altro workspace.
{
"statusCode": 403,
"error": "Forbidden",
"code": "workspace_access_denied",
"workspaceId": "cm8ws4c5d6",
"message": "Non hai accesso al workspace cm8ws4c5d6. Chiama GET /workspaces per elencare i workspace che puoi usare e invia uno di quegli id nell'header X-Workspace-Id."
}Formato della risposta
Le risposte riuscite restituiscono lo stato 200 OK con un corpo strutturato così:
{
"status": "success",
"data": { ... }
}Gli errori usano il formato standard delle risposte di errore HTTP di NestJS.
{
"message": "Unauthorized",
"statusCode": 401
}Codici di errore standard
<strong>400 Bad Request</strong> -- L'input non è valido o mancano parametri obbligatori, ad esempio un token del workspace senzawebsiteId o domain. Anche una chiave del sito che chiama GET /workspaces riceve 400.<br /><strong>401 Unauthorized</strong> -- Il token API manca, non è valido o è stato revocato. Il codice token_issuer_lost_access indica che il membro che ha creato la chiave ha perso l'accesso al workspace; crea una nuova chiave.<br /><strong>403 Forbidden</strong> -- workspace_access_denied: l'header X-Workspace-Id indica un workspace che questa credenziale non può raggiungere. subscription_required: il piano non include più l'accesso API. permission_denied: il tuo ruolo nel workspace non ha il permesso flowsery.write, che hanno Amministratori ed Editor. Durante la prova gratuita, i problemi rilevati dall'AI oltre i primi 10 rispondono "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- La risorsa richiesta non esiste.<br /><strong>429 Too Many Requests</strong> -- Più di 600 richieste in un minuto per questa chiave. Attendi il numero di secondi indicato in Retry-After. Ogni risposta include RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.<br /><strong>500 Internal Server Error</strong> -- Si è verificato un problema imprevisto sul server.curl --request GET \
--url https://analytics.flowsery.com/analytics/api/v1/websites \
--header 'Authorization: Bearer <workspace-api-token>'{
"status": "success",
"data": [
{
"id": "cm8abc123",
"domain": "example.com",
"timezone": "America/New_York",
"currency": "USD",
"trackingId": "flid_abc123"
}
]
}