api-reference

1. Crea un token API o una clave de sitio web

Crea un token API de workspace desde la página API Tokens cuando necesites acceso programático a todos los sitios web del workspace, incluidas integraciones MCP y OpenClaw. Los tokens de workspace usan el prefijo <code>flow_ws_</code>. Para tracking servidor a servidor de un solo sitio, crea una clave API de sitio web desde Settings > API de ese sitio; las claves de sitio usan el prefijo <code>flow_</code>. Copia los tokens nuevos de inmediato porque el secreto solo se muestra una vez.

2. Autenticar sus solicitudes

Cada llamada API debe incluir el encabezado Authorization con el esquema Bearer. Usa un token de workspace <code>flow_ws_</code> para acceso API multi-sitio, o una clave de sitio web <code>flow_</code> para un solo sitio.

Encabezado de autorizacion
Authorization: Bearer YOUR_API_KEY

3. Comenzar a hacer solicitudes

La URL base para todos los endpoints v1 es: <code>https://analytics.flowsery.com/analytics/api/v1/</code>. Con un token de workspace, llama primero a <code>GET /websites</code> y luego pasa <code>websiteId</code> o <code>domain</code> en las solicitudes. Las claves de sitio web ya están limitadas a un sitio y no necesitan selector.

Elegir un workspace

Cada llamada se ejecuta en un workspace. Sin la cabecera opcional <code>X-Workspace-Id</code> cae en tu workspace predeterminado. Un inicio de sesión OAuth, como el conector de Claude o ChatGPT, puede llegar a todos los workspaces a los que pertenece su miembro, en todas sus organizaciones: llama a <code>GET /workspaces</code> para listarlos y envía el id que quieras en <code>X-Workspace-Id</code> en cada solicitud. Una clave API pertenece a un workspace, así que envía su propio id o no incluyas la cabecera.

Cabecera de workspace
X-Workspace-Id: cm8ws1a2b3

Un workspace al que el llamante no puede acceder responde <code>403 Forbidden</code> con el código <code>workspace_access_denied</code>. Una clave API o clave de sitio web enviada con el id de otro workspace recibe el mismo error.

Error de acceso al workspace
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "cm8ws4c5d6",
  "message": "No tienes acceso al espacio de trabajo cm8ws4c5d6. Llama a GET /workspaces para ver los espacios de trabajo que puedes usar y envía uno de esos ids en la cabecera X-Workspace-Id."
}

Formato de respuesta

Las respuestas exitosas devuelven un estado 200 OK con un cuerpo estructurado asi:

Respuesta exitosa
{
  "status": "success",
  "data": { ... }
}

Los errores utilizan la forma de respuesta de error HTTP normal de NestJS.

Respuesta de error
{
  "message": "Unauthorized",
  "statusCode": 401
}

Codigos de error estandar

<strong>400 Bad Request</strong> -- La entrada no es válida o faltan parámetros requeridos, por ejemplo un token de workspace sin <code>websiteId</code> ni <code>domain</code>. Una clave de sitio que llama a <code>GET /workspaces</code> también recibe 400.<br /><strong>401 Unauthorized</strong> -- Falta el token API, no es válido o fue revocado. El código <code>token_issuer_lost_access</code> significa que el miembro que creó la clave perdió el acceso al workspace; crea una clave nueva.<br /><strong>403 Forbidden</strong> -- <code>workspace_access_denied</code>: la cabecera X-Workspace-Id indica un workspace al que esta credencial no puede acceder. <code>subscription_required</code>: el plan ya no incluye acceso a la API. <code>permission_denied</code>: tu rol en el workspace no tiene el permiso <code>flowsery.write</code>, que tienen los Admins y los Editors. Durante la prueba gratuita, los problemas detectados por la IA más allá de los 10 primeros responden "Upgrade to view this issue".<br /><strong>404 Not Found</strong> -- El recurso solicitado no existe.<br /><strong>429 Too Many Requests</strong> -- Más de 600 solicitudes en un minuto para esta clave. Espera los segundos indicados en <code>Retry-After</code>. Cada respuesta incluye <code>RateLimit-Policy</code>, <code>RateLimit-Limit</code>, <code>RateLimit-Remaining</code> y <code>RateLimit-Reset</code>.<br /><strong>500 Internal Server Error</strong> -- Se produjo un problema inesperado en el servidor.
Solicitud de ejemplo (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"
    }
  ]
}