# 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, keeps the catalog current and releases a
specification as a Git tag.

You need the CLI installed; the [Quickstart](/docs/quickstart) shows how. `apigenie-catalog` is
[experimental](/docs/reference/cli#experimental-commands): 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`.

## Release a specification

`apigenie-catalog release` (since 0.12.0) makes a release a Git tag, so everyone who clones the
repository has it. Bump `info.version` in the pull request that changes the API, merge it, then
tag:

```text
$ apigenie-catalog release orders-api 1.1.0 --push
Tagged orders-api-1.1.0 at b2e21b5 Release 1.1.0 of the Orders API (previous release: 1.1.0-rc.1, tag orders-api-1.1.0-rc.1)
Pushed orders-api-1.1.0 to origin
```

The command refuses to tag when the version is not above the latest release, the file has changes
that are not committed, or its `info.version` is not `1.1.0`. The tag and the `info.version` of an
OpenAPI, AsyncAPI or Swagger document then name the same version. `apigenie-catalog versions`
lists the releases:

```text
$ apigenie-catalog versions orders-api
VERSION     TAG                    COMMIT
1.1.0       orders-api-1.1.0       b2e21b5 2026-11-02
1.1.0-rc.1  orders-api-1.1.0-rc.1  c121c1b 2026-10-28
1.0.0       orders-api-1.0.0       12e9f3d 2026-10-12
```

The tags are revisions, so
`apigenie changelog apis/orders/openapi.yaml --from orders-api-1.0.0 --to orders-api-1.1.0` lists
the changes between two releases ([changelog](/docs/reference/cli/changelog)).

Teams that tag `orders-api/v1.4.0` set `catalog.tags.pattern` to `{name}/v{version}`.

Mark an API that is on its way out in the catalog section, so that the catalog says so and a
retired one can't be released by mistake:

```yaml
catalog:
  specs:
    - name: legacy-billing
      path: apis/legacy/billing.yaml
      owner: team-finance
      lifecycle: deprecated
      sunset: 2027-03-31
```

```text
$ apigenie-catalog list
NAME             FORMAT           VERSION  OWNER          LIFECYCLE                PATH                      COMMIT
legacy-billing   OpenAPI 3.0.3    4.2.0    team-finance   deprecated (2027-03-31)  apis/legacy/billing.yaml  a510f31 2026-11-02
orders-api       OpenAPI 3.1.0    1.1.0    team-commerce  active                   apis/orders/openapi.yaml  b2e21b5 2026-11-02
acme-pricing-v1  Protobuf proto3  -        -              active                   proto/pricing.proto       12e9f3d 2026-10-12
```

Once `lifecycle: retired` replaces `deprecated`, `apigenie-catalog release legacy-billing 4.2.0`
prints `legacy-billing is retired (catalog section); a retired specification is not released` and
`legacy-billing 4.2.0 is not released` on the standard error, and exits with status 2.

## 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, owner and lifecycle 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.
