---
title: "Entries, attributes & relationships"
description: "How to define catalog types and their attributes, add entries, link entries to each other, and sync entries from external tools."
canonical: https://firefight.app/docs/catalog/entries-and-attributes/
---

# Entries, attributes & relationships

Everything in the catalog follows one shape. A type defines a schema of attributes, and entries fill that schema in. This page walks through defining both, plus the relationships that connect entries and the API path for keeping entries in sync from outside tools.

## Creating and editing types

On the **Catalogue** page, **Create Type** opens a dialog where you name the type, describe it, pick an icon and a color, and define its attributes. On a type's own page, **Edit Type** opens the same dialog for changes. You can edit built-in types too, including adding attributes to them.

## Attributes

Each attribute has a name, a kind, and an optional required flag. These are the kinds you can choose.

| Kind | What it holds |
|---|---|
| Text | Free-form text, such as a description or a repository URL |
| Number | A numeric value |
| Boolean | A yes or no flag, such as Is Production |
| Select | One choice from a fixed list of options you define |
| List | A list of values |
| Reference | A link to an entry of another catalog type you pick, such as a service's Owner Team |
| Slack Channel | A Slack channel |
| Member | One workspace member |
| Members | Multiple workspace members |

A Select attribute requires at least one option. A Reference attribute requires you to pick which type it points at. An attribute's kind is fixed after creation, so if you need a different kind, add a new attribute instead.

The built-in types ship with these attributes.

| Type | Default attributes |
|---|---|
| Team | Description, Slack Channel, Manager, Members |
| Service | Description, Owner Team (references Team), Tier (Critical, Standard, or Internal), Repository, Slack Channel |
| Environment | Description, Is Production, Region |
| Functionality | Description, Owner Team (references Team) |

## Entries

On a type's page, **Add** opens a form with a field for the entry's name and one field per attribute. Entries appear in the table with their attribute values as columns. Clicking an entry opens a detail panel showing every attribute, when the entry was created and last updated, and actions to edit or delete it.

Each entry gets a slug derived from its name, lowercased with underscores, such as `payment_service` for "Payment Service". The slug is the entry's stable identifier. It cannot change after creation, it must be unique within the type, and it is what alerts and the API match against.

:::note
Alert enrichment matches an alert's `service` field against service entry slugs. Name your entries so their slugs line up with what your monitoring tools send, or configure your tools to send the slug.
:::

## Relationships

Relationships between entries come from Reference attributes. When you set a service's Owner Team, Firefight stores a relationship from that service to that team. Clearing the attribute removes the relationship.

These links are what make the catalog a map rather than a list. The owning-team features in alert routing follow the service to team relationship, and connected AI agents see each entry's relationships when they search the catalog. See [Putting the catalog to work](https://firefight.app/docs/catalog/using-catalog.md).

## Entries managed by external tools

If a service registry, an infrastructure repo, or a script is the source of truth for part of your catalog, push entries through the API instead of maintaining them by hand. When a create request includes a `source` (the name of the pushing system) and an `external_id` (its identifier there), Firefight treats the pair as the entry's identity. Pushing the same pair again updates the existing entry instead of creating a duplicate, so a sync job can run repeatedly and stay idempotent. Both values must be provided together.

API keys are minted under **Settings → API Keys** and need catalog scopes for these endpoints.

| Request | What it does |
|---|---|
| `GET /api/v1/catalog/types` | List types with their attribute definitions |
| `GET /api/v1/catalog/types/:slug` | Fetch one type |
| `GET /api/v1/catalog/types/:slug/entries` | List a type's entries |
| `POST /api/v1/catalog/types/:slug/entries` | Create an entry, or update it when `source` and `external_id` match an existing one |
| `GET /api/v1/catalog/entries/:id` | Fetch one entry |
| `PATCH /api/v1/catalog/entries/:id` | Update an entry's name or attributes |
| `DELETE /api/v1/catalog/entries/:id` | Delete an entry |