<!-- Source: https://docs.squirro.com/en/latest/technical/neo/dev-guide/squirro-api.html -->
# Squirro API

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/neo-core/api`. It returns area-grouped clients (`items`, `facets`, `files`, `conversations`, and `groups`) plus `fetch` and `buildPath` escape hatches for endpoints the grouped clients do not cover, and exposes the current `tenant` and `projectId` as fields you can read. Both are injected into every request automatically, so you do not pass them yourself:

```jsx
import { useQuery } from '@tanstack/react-query';
import { useSquirroApi } from '@squirro/neo-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.

The `groups` client lists the user groups of the tenant with `api.groups.list()`. That call requires an administrator or project owner token, so use it for configuration work rather than for a check at runtime. To find out which groups the current viewer belongs to, read the `groups` field returned by `useCurrentUser()`, described on the [Building Dashboard Components](building-dashboards.md#neo-extensions-building-dashboards) page.

## 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. The chat widget uses the same bindings through its data source. For more information, see the [The Chat Widget](chat-widget.md#neo-extensions-chat-widget) page.

> **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](../../api/authentication.md#api-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:

```jsx
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](../../api/services/index.md#api-services) page.
- For an overview of all available APIs and SDKs, see the [APIs and SDKs](../../api/index.md#api) page.
- For common response status codes and request headers, see the [Common Status Codes](../../api/common-status.md#api-common-status) and [Common Headers](../../api/common-headers.md#api-common-headers) pages.