---
title: "List or search workspace families"
method: GET
path: "/v1/workspaces/{workspaceId}/families"
tags: ["Families"]
---

# List or search workspace families

`GET /v1/workspaces/{workspaceId}/families`

## Request

- Base URL: `https://external-api.pirros.com`
- URL: `https://external-api.pirros.com/v1/workspaces/{workspaceId}/families`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.pirros.com/oauth/token`

List families in a workspace. Without `q`, structured filters (tag, category, revit_version) run in SQL and the result is keyset-paginated by (created_at, id). With `q`, a free-text Algolia search runs (requires a broad family grant, else 403 free_text_requires_broad_access) with the same structured filters applied as facets. The cursor is opaque. With `q`, a cursor reused under a changed query resets to the first page. Without `q`, the cursor encodes ordering position only and continues from that position under the new filters; re-paginate from the start when filters change. `revit_version` matches a family’s available-version set (authored or successfully upgraded) and is normalized to a 4-digit year. An unrecognized revit_version (no standalone 4-digit year) matches nothing and returns an empty result — it is not rejected.

## Path parameters

- `workspaceId` string, uuid, required

## Query parameters

- `q` string
- `tag` string
- `category` string
- `revit_version` string
- `cursor` string
- `limit` string

## Response `200`

Families list/search results

- ExternalFamilyListResponse: Cursor-paginated families list/search results
  - `response` object, required
    - `data` ExternalFamilySummaryDto[], required
      - `id` string, uuid, required
      - `name` string, required
      - `category` string, required
      - `classification` string, required
      - `revit_version` string, required
    - `next_cursor` string, nullable, required
    - `expanded` object, required
  - `meta` object, required
    - `request_id` string, uuid, required

## Other responses

- `400`: Invalid request (bad path param, query param, or cursor)
- `401`: Unauthorized (invalid or missing token)
- `403`: Forbidden — either no resource filter grants access to this list (insufficient_scope), or a free-text `?q=` search was attempted with a narrow (non-broad) family grant (free_text_requires_broad_access). Free-text search requires a broad family grant.
- `429`: Rate limit exceeded (1000 requests per hour per client)
- `503`: External API temporarily disabled by operator kill switch (service_unavailable)

---

[API](https://skmtc.dev/pirros/apis/pirros-external-api.md) - [All operations](https://skmtc.dev/pirros/apis/pirros-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pirros/apis/pirros-external-api/revisions/01c66b8d9fd1?raw)