# Catalog the APIs of a repository

Source: https://apigenie.pl/docs/guides/catalog-the-apis-of-a-repository

A repository with more than a few APIs raises questions nobody can answer quickly: which APIs are
there, which version is which, and who to ask about each. `apigenie-catalog` answers them from the
repository itself, with nothing to host and nothing to upload. This guide lists the APIs of a
repository, records their names and owners, and keeps the catalog current.

You need the CLI installed; the [Quickstart](/docs/quickstart) shows how. `apigenie-catalog` is
[experimental](/docs/reference/cli/overview#experimental-commands): release tags, pinned consumers
and catalogs that span several repositories will add options.

## List the specifications

Run it anywhere in the repository; no configuration is needed:

```sh
apigenie-catalog list
```

```text
NAME             FORMAT           VERSION  PATH                      COMMIT
order-events     AsyncAPI 3.0.0   2.0.0    apis/events.json          96175d8 2026-10-12
orders-api       OpenAPI 3.1.0    1.2.0    apis/orders/openapi.yaml  4d0c2e1 2026-10-14
schema           GraphQL          -        graphql/schema.graphql    96175d8 2026-10-12
acme-pricing-v1  Protobuf proto3  -        proto/pricing.proto       96175d8 2026-10-12
```

It looks at the files Git tracks, so build output and ignored files stay out, and finds OpenAPI,
AsyncAPI and Swagger documents by their content, every `.proto` file, and GraphQL files with type
definitions. Each row has a name derived from the specification (its title, its Protobuf package or
its file name), its format and version, its path and its last commit. Give a directory to list part
of the repository: `apigenie-catalog list apis/`.

## Give each API a name and an owner

A derived name changes when the title or the file does, and an owner can't be derived at all.
`apigenie-catalog init` writes a `catalog` section into `apigenie.yaml`, with one entry per
specification:

```sh
apigenie-catalog init
```

```yaml
catalog:
  specs:
    - name: order-events
      path: apis/events.json
      owner: null
    - name: orders-api
      path: apis/orders/openapi.yaml
      owner: null
```

Fill in the owners, and change a name where the derived one isn't right. From then on the name stays
when the file moves: change the `path` and keep the `name`. Commit the file: a new owner is now a
change that is reviewed like any other.

Leave files out of the catalog, such as test fixtures, with patterns under `catalog.exclude`; see
[the catalog section](/docs/reference/cli/configuration#catalog) of the configuration.

## Keep it current

Run `init` again after adding specifications. New ones are added, the entries you edited stay as
they are, and the entries whose files are gone are reported; `--prune` removes them:

```text
$ apigenie-catalog init
Updated /home/me/specs/apigenie.yaml: 2 added, 4 kept, 1 not found
  added apis/billing.yaml
  added apis/orders-v2.yaml
  not found legacy/swagger.yaml
Remove the entries of the files that are gone with --prune.
```

To catch a specification added without an entry, let CI run `init --dry-run`, which prints the file
instead of writing it, and compare the result with the committed `apigenie.yaml`.

## Use the catalog in your tools

`--json` prints the catalog with a [published schema](https://apigenie.pl/schemas/apigenie-catalog-report.json):
the name, title, format, version, path and owner of each specification, its last commit, and
whether the catalog section lists it. Scripts can lint or diff every API of the repository from it,
or feed a dashboard of owners:

```sh
apigenie-catalog list --json > catalog.json
```

## Next steps

- [apigenie-catalog](/docs/reference/catalog): every option and the JSON report.
- [changelog](/docs/reference/cli/changelog): the history of each specification from git.
- [Lint and format API descriptions](/docs/guides/lint-and-format-api-descriptions): the same rules
  for every API the catalog lists.