---
title: "Search catalog entities"
method: GET
path: "/api/rest/v1/catalog/search"
tags: ["Catalog"]
---

# Search catalog entities

`GET /api/rest/v1/catalog/search`

## Request

- Base URL: `https://app.componecat.ai`
- URL: `https://app.componecat.ai/api/rest/v1/catalog/search`
- Auth: none required

Full-text and structured search with relevance ranking and facet counts.

**Query language (`q`).** Plain words match names, descriptions, tags and documentation.
Structured clauses use `field:value` (e.g. `kind:component`, `lifecycle:production`,
`owner:payments`, `tag:backend`, `language:go`, `namespace:payments`) and combine
with `AND`, `OR`, `NOT` and parentheses, e.g.
`lifecycle:production AND (language:go OR language:rust)`. An invalid query returns `400`
with `code`, `position`, `token` and `suggestions` extensions.

**Custom field filters.** Any number of `fields.{key}` query parameters, where `{key}` is a
field definition key:
- `fields.{key}={value}` — equals the value
- `fields.{key}=__null` / `fields.{key}=__notnull` — the field is unset / set
- `fields.{key}=__contains:{value}` — a MultiSelect or Tag field contains the value

These compile to the same clauses as `q`, and all filters combine with AND.

**Pagination** is offset-based: `limit` + `offset`, with `totalCount` in the result.

## Query parameters

- `q` string
- `limit` union
  - integer
  - string, int32
- `offset` union
  - integer
  - string, int32
- `kindId` string
- `lifecycle` string
- `ownerId` string
- `tag` string
- `language` string
- `namespace` string
- `sortByField` string
- `sortDescending` boolean

## Response `200`

OK

- RestApiResponseOfCatalogSearchRestResult: Standard REST API response envelope for a single resource.
  - `data` CatalogSearchRestResult, required: Search result for the REST search endpoint, including ranked items and facet counts.
    - `items` CatalogSearchResultItemDto[], required: The requested page of matches, most relevant first unless `sortByField` is set.
      - `id` string, uuid, required: The entity ID.
      - `name` string, required: URL-safe identifier (lowercase slug).
      - `namespace` string, nullable, required: Optional logical grouping namespace. Null when the entity has none.
      - `displayName` string, required: Human-readable name.
      - `kindId` string, uuid, required: ID of the entity kind definition.
      - `ownerId` string, uuid, required: ID of the owning team.
      - `lifecycle` 'EXPERIMENTAL' | 'DEVELOPMENT' | 'PRODUCTION' | 'DEPRECATED' | 'RETIRED', required: Lifecycle stage.
      - `description` string, required: Human-readable description.
      - `rank` union, required: Relevance score; higher is more relevant. Only comparable within one result set.
        - number, double
        - string, double
      - `fields` object, nullable, required: Current custom field values as a JSON object keyed by field definition `key`, with native JSON value types — the same shape accepted by the create/update `fieldValues` input, so a value read back can be sent straight into an update. An empty object when no field values are set.
      - `docSnippet` string, nullable: Excerpt of the documentation section that matched the text query, when the match came from documentation.
      - `docSectionTitle` string, nullable: Title of the documentation section `docSnippet` came from.
    - `totalCount` union, required: Total number of matches across all pages.
      - integer
      - string, int32
    - `facets` CatalogSearchFacetsDto, required: Facet counts for the search result, grouped by dimension.
      - `kinds` KindFacetDto[], required: Match counts per entity kind.
        - `kindId` string, uuid, required: ID of the entity kind definition.
        - `kindKey` string, required: Key of the kind, e.g. `component`.
        - `count` union, required: Number of matches of this kind.
          - integer
          - string, int32
      - `lifecycles` LifecycleFacetDto[], required: Match counts per lifecycle stage.
        - `value` 'EXPERIMENTAL' | 'DEVELOPMENT' | 'PRODUCTION' | 'DEPRECATED' | 'RETIRED', required: Lifecycle stage.
        - `count` union, required: Number of matches in this stage.
          - integer
          - string, int32
      - `owners` OwnerFacetDto[], required: Match counts per owning team.
        - `ownerId` string, uuid, required: ID of the owning team.
        - `ownerName` string, required: Name of the owning team.
        - `count` union, required: Number of matches owned by this team.
          - integer
          - string, int32
      - `tags` TagFacetDto[], required: Match counts per tag.
        - `value` string, required: The tag.
        - `count` union, required: Number of matches carrying this tag.
          - integer
          - string, int32
      - `fields` FieldFacetDto[], required: Match counts per value of each facetable custom field.
        - `key` string, required: Field definition key; filter on it with `fields.{key}=`.
        - `displayName` string, required: Field definition display name.
        - `values` FieldValueFacetDto[], required: Match counts per value of this field.
          - `value` string, required: The field value, as a string.
          - `count` union, required: Number of matches with this value.
            - integer
            - string, int32

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests

---

[API](https://skmtc.dev/componecat/apis/componecat-rest-api.md) · [All operations](https://skmtc.dev/componecat/apis/componecat-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/componecat/apis/componecat-rest-api/revisions/6c53d4984720?raw)