Squirro API

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

Your dashboards can fetch data from the Squirro API. For the common item and facet endpoints, use the typed client, which is the recommended path. For anything the typed client does not cover, fall back to a raw fetch call. Either way, authentication is handled automatically. No manual token management is required.

The Typed Client (Recommended)

The typed client is the recommended way to call the Squirro API. Import useSquirroApi() from @squirro/nextgen-core/api. It returns area-grouped clients (items and facets) plus fetch and buildPath escape hatches for endpoints the grouped clients do not cover. The client injects the current tenant and projectId automatically, so you do not pass them yourself:

import { useQuery } from '@tanstack/react-query';
import { useSquirroApi } from '@squirro/nextgen-core/api';

export default function Analytics({ projectId }: { projectId: string }) {
  const api = useSquirroApi();
  const { data } = useQuery({
    queryKey: ['items', projectId, 'lithium'],
    queryFn: () => api.items.search({ query: 'lithium', count: 20 }),
  });

  return <div>{data?.items.length ?? 0} results</div>;
}

The bundle scaffold installs a squirro-api skill under .claude/skills/ with the full request and response schemas, which is a useful reference when building queries.

How Authentication Works

• During local development

  The dev proxy injects a valid access token into all API requests on your behalf.

• In production

  The webclient server handles authentication via session cookies on the same origin.

The same fetch paths work in both environments. No code changes are needed when deploying.

Note

The Squirro API uses a refresh token and access token model. In bundles, that exchange is handled automatically. You never interact with tokens directly. For background on how Squirro authentication works, see the Authentication page.

Raw Fetch with React Query

For endpoints the typed client does not cover, call them with a raw fetch wrapped in @tanstack/react-query, which handles caching, loading states, and error states:

import { useQuery } from '@tanstack/react-query';

interface Props {
  projectId: string;
}

export default function Analytics({ projectId }: Props) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['my-data', projectId],
    queryFn: async () => {
      const response = await fetch(`/api/your-endpoint?project_id=${encodeURIComponent(projectId)}`);
      if (!response.ok) throw new Error('Request failed');
      return response.json();
    },
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading data</div>;

  return <div>{JSON.stringify(data)}</div>;
}

Tip

Always include projectId in your query keys. When you switch projects, React Query automatically refetches with the new project ID.

API Documentation

The Squirro platform exposes its functionality through a set of REST APIs. The following references cover the available endpoints, request formats, and response schemas:

• For the full microservices REST API reference, see the Microservices APIs page.

• For an overview of all available APIs and SDKs, see the APIs and SDKs page.

• For common response status codes and request headers, see the Common Status Codes and Common Headers pages.