Catalog API¶

The Catalog API provides endpoints for managing software components in the Farm catalog.

For interactive documentation, including all available endpoints, data models, and request/response examples, please refer to the Swagger UI.

Endpoints¶

Filtering by Domain Group¶

The GET /api/v1/catalog/components endpoint supports a kindGroup query parameter to filter components by team domain:

Example:

# List only infrastructure components
curl -H "Authorization: Bearer <token>" \
  http://localhost:3000/api/v1/catalog/components?kindGroup=infra

Filtering by Team¶

The GET /api/v1/catalog/components endpoint accepts a teamId query parameter to return only components owned by the specified team.

Example:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/v1/catalog/components?teamId=<team-uuid>"

The teamId filter can be combined with kindGroup and pagination parameters.

Pagination¶

All list endpoints return paginated responses. The following query parameters are supported:

Example:

# List components with pagination and filtering
curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/v1/catalog/components?kindGroup=infra&skip=0&take=10"

Paginated Response Format¶

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "my-service",
      "kind": "service",
      "owner": "platform-engineering",
      "lifecycle": "production"
    }
  ],
  "total": 42,
  "skip": 0,
  "take": 10
}

Caching¶

The following GET endpoints use automatic response caching:

Cache is automatically invalidated when components are created, updated, deleted, or registered via YAML. No manual cache management is required.