# Catalog API

Version 1.0 · OpenAPI 3.1.0

Read and describe EvoHub Catalog from scripts and CI: declare services
with their owner, tier and links, read what agents and cloud accounts
found running, decide the match queue, read drift, the service map and
each service's SLA report, manage tiers, environments and cloud accounts,
and export the inventory for an audit.

**Authentication.** Every endpoint takes an EvoHub API key, sent as
`Authorization: Bearer evohub_…` or as `X-API-Key: evohub_…`. Each
operation names the scopes the key needs in its description and in
`x-evohub-permission`; where two are listed, the key needs both. A
missing or invalid key gets **401**; a valid key without the scope gets
**403**, never 401. A key is held to its scopes even when it was created
by an administrator. See the [API overview](/api-overview),
[API keys and scopes](/api-keys-and-scopes) and [Errors](/errors).

**Responses.** A successful answer carries its result in `data`. A list
that pages also carries `pagination`: `next_cursor` (null on the last
page), `has_more` and, on some lists' first page, `total`. Pass
`next_cursor` back as `cursor` for the next page; `limit` is 20 by
default and at most 100. Errors carry an `error` object with a
machine-readable `code`. Timestamps are RFC 3339 in UTC. Request bodies
are strict: a field the endpoint does not know is refused with
`INVALID_BODY` rather than ignored.

**Declared and observed.** Services, tiers, responsibilities and
environments are what people declare. Resources, applications, images,
changes and the map are what agents and cloud accounts observed; they are
read-only here, except deciding which service a resource or application
belongs to.

**Agents.** The routes under `/api/v1/catalog/ingest/` are called by the
EvoHub agent only, signed with the agent's own key. API keys cannot call
them, and they are not part of this reference.

## Servers

- `https://evohub.io`

## Authentication

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Services

What your teams declared, its responsibilities and its SLA report.

- [GET /api/v1/catalog/components](https://docs.evohub.io/catalog/list-components.md): List services
- [POST /api/v1/catalog/components](https://docs.evohub.io/catalog/create-component.md): Declare a service
- [GET /api/v1/catalog/components/{ref}](https://docs.evohub.io/catalog/get-component.md): Get a service
- [DELETE /api/v1/catalog/components/{ref}](https://docs.evohub.io/catalog/delete-component.md): Delete a service
- [PATCH /api/v1/catalog/components/{ref}](https://docs.evohub.io/catalog/update-component.md): Change a service
- [GET /api/v1/catalog/components/{ref}/resources](https://docs.evohub.io/catalog/list-component-resources.md): List a service's resources
- [PUT /api/v1/catalog/components/{ref}/responsibilities](https://docs.evohub.io/catalog/set-component-responsibilities.md): Set a service's RACI
- [GET /api/v1/catalog/components/{ref}/sla-report](https://docs.evohub.io/catalog/get-component-slareport.md): Get a service's SLA report

## Matches

Which service a resource or an application belongs to.

- [GET /api/v1/catalog/matches](https://docs.evohub.io/catalog/list-matches.md): List match proposals
- [POST /api/v1/catalog/matches/{id}/accept](https://docs.evohub.io/catalog/accept-match.md): Accept a proposal
- [POST /api/v1/catalog/matches/{id}/reject](https://docs.evohub.io/catalog/reject-match.md): Reject a proposal
- [POST /api/v1/catalog/resources/{id}/component](https://docs.evohub.io/catalog/bind-resource.md): Put a resource in a service
- [POST /api/v1/catalog/applications/{id}/component](https://docs.evohub.io/catalog/bind-application.md): Put an application in a service

## Resources

What agents and cloud accounts observed, its history and its changes.

- [GET /api/v1/catalog/resources](https://docs.evohub.io/catalog/list-resources.md): List resources
- [GET /api/v1/catalog/resources/{id}](https://docs.evohub.io/catalog/get-resource.md): Get a resource
- [GET /api/v1/catalog/resources/{id}/changes](https://docs.evohub.io/catalog/list-resource-changes.md): List a resource's changes
- [GET /api/v1/catalog/resources/{id}/changes/{change}/diff](https://docs.evohub.io/catalog/get-resource-change-diff.md): Get what a change changed
- [GET /api/v1/catalog/changes](https://docs.evohub.io/catalog/list-changes.md): List recent changes
- [GET /api/v1/catalog/images](https://docs.evohub.io/catalog/list-images.md): List container images

## Applications

Resources grouped the way they run together, the namespaces and the service map.

- [GET /api/v1/catalog/applications](https://docs.evohub.io/catalog/list-applications.md): List applications
- [GET /api/v1/catalog/applications/{id}](https://docs.evohub.io/catalog/get-application.md): Get an application
- [GET /api/v1/catalog/applications/{id}/graph](https://docs.evohub.io/catalog/get-application-graph.md): Get an application's graph
- [GET /api/v1/catalog/namespaces](https://docs.evohub.io/catalog/list-namespaces.md): List namespaces
- [GET /api/v1/catalog/map](https://docs.evohub.io/catalog/get-service-map.md): Get the service map

## Drift

Where what was declared and what runs disagree.

- [GET /api/v1/catalog/drift](https://docs.evohub.io/catalog/get-drift.md): Get drift

## Tiers

The organization's tiers and the SLA targets they promise.

- [GET /api/v1/catalog/tiers](https://docs.evohub.io/catalog/list-tiers.md): List tiers
- [POST /api/v1/catalog/tiers](https://docs.evohub.io/catalog/create-tier.md): Create a tier
- [PUT /api/v1/catalog/tiers/order](https://docs.evohub.io/catalog/reorder-tiers.md): Reorder tiers
- [PATCH /api/v1/catalog/tiers/{id}](https://docs.evohub.io/catalog/update-tier.md): Change a tier
- [POST /api/v1/catalog/tiers/{id}/archive](https://docs.evohub.io/catalog/archive-tier.md): Archive a tier
- [GET /api/v1/catalog/tiers/{id}/versions](https://docs.evohub.io/catalog/list-tier-versions.md): List a tier's versions

## Environments

The places things run, declared by people.

- [GET /api/v1/catalog/environments](https://docs.evohub.io/catalog/list-environments.md): List environments
- [POST /api/v1/catalog/environments](https://docs.evohub.io/catalog/create-environment.md): Create an environment
- [GET /api/v1/catalog/environments/{id}](https://docs.evohub.io/catalog/get-environment.md): Get an environment
- [DELETE /api/v1/catalog/environments/{id}](https://docs.evohub.io/catalog/delete-environment.md): Delete an environment
- [PATCH /api/v1/catalog/environments/{id}](https://docs.evohub.io/catalog/update-environment.md): Change an environment

## Sources

Where observations come from — agents and cloud accounts.

- [GET /api/v1/catalog/sources](https://docs.evohub.io/catalog/list-sources.md): List sources
- [GET /api/v1/catalog/sources/{id}](https://docs.evohub.io/catalog/get-source.md): Get a source
- [PATCH /api/v1/catalog/sources/{id}](https://docs.evohub.io/catalog/update-source.md): Rename, pause or resume a source

## Cloud accounts

AWS, Azure, GCP and portvMind accounts the catalog reads itself.

- [GET /api/v1/catalog/connections/setup](https://docs.evohub.io/catalog/get-cloud-setup.md): Get what a connection needs
- [GET /api/v1/catalog/connections](https://docs.evohub.io/catalog/list-connections.md): List cloud accounts
- [POST /api/v1/catalog/connections](https://docs.evohub.io/catalog/create-connection.md): Connect a cloud account
- [GET /api/v1/catalog/connections/{id}](https://docs.evohub.io/catalog/get-connection.md): Get a cloud account
- [DELETE /api/v1/catalog/connections/{id}](https://docs.evohub.io/catalog/delete-connection.md): Disconnect a cloud account
- [PATCH /api/v1/catalog/connections/{id}](https://docs.evohub.io/catalog/update-connection.md): Change a cloud account
- [POST /api/v1/catalog/connections/{id}/pause](https://docs.evohub.io/catalog/pause-connection.md): Pause a cloud account
- [POST /api/v1/catalog/connections/{id}/resume](https://docs.evohub.io/catalog/resume-connection.md): Resume a cloud account
- [POST /api/v1/catalog/connections/{id}/check](https://docs.evohub.io/catalog/check-connection.md): Check a cloud account
- [GET /api/v1/catalog/connections/{id}/template](https://docs.evohub.io/catalog/get-connection-template.md): Download the AWS role template
- [GET /api/v1/catalog/connections/{id}/architecture](https://docs.evohub.io/catalog/get-connection-architecture.md): Get an account's architecture

## Export

The inventory, for an audit.

- [GET /api/v1/catalog/exports/inventory](https://docs.evohub.io/catalog/export-inventory.md): Export the inventory