# Service Catalog Entity Metadata API

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fservice-catalog-entity-metadata-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fservice-catalog-entity-metadata-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

The **Service Catalog Entity Metadata API** attaches an **owner**, a **VCS repository link**, and free-form **annotations** to any entity in the APM [Service Catalog](https://coralogix.com/docs/user-guides/apm-v2/services.md) - services, databases, and other entity types. Use it to set ownership and repository links in bulk, from CI, or alongside your infrastructure-as-code, instead of editing each entity by hand.

Preview

This API is in preview. Its shape may change before general availability.

## What you need[​](#what-you-need "Direct link to What you need")

* A personal or team [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md).
* The `service-catalog-config:Read` permission for read operations, and `service-catalog-config:Update` for write operations.

## Authentication[​](#authentication "Direct link to Authentication")

Pass your API key as a bearer token in the `Authorization` header:

```
Authorization: Bearer <cx_api_key>
```

## Endpoint[​](#endpoint "Direct link to Endpoint")

This API is served from the Coralogix management endpoint. Select the `api.eu2.coralogix.com:443` endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md) using the domain selector at the top of the page. All paths are under:

```
https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2
```

## Endpoints[​](#endpoints "Direct link to Endpoints")

| Method   | Path                             | Description                                                                                                            | Permission                      |
| -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `PUT`    | `/{entity_type}/entities/{name}` | **Replace** an entity's metadata. Creates it if none exists, otherwise fully replaces it - omitted fields are cleared. | `service-catalog-config:Update` |
| `PATCH`  | `/{entity_type}/entities/{name}` | **Update** an entity's metadata. Only the fields you send change; fails with `404` if the entity has no metadata yet.  | `service-catalog-config:Update` |
| `GET`    | `/{entity_type}/entities/{name}` | Get one entity's metadata.                                                                                             | `service-catalog-config:Read`   |
| `GET`    | *(base path)*                    | List metadata, optionally filtered to one entity type (up to 1,000 rows).                                              | `service-catalog-config:Read`   |
| `DELETE` | `/{entity_type}/entities/{name}` | Remove an entity's metadata.                                                                                           | `service-catalog-config:Update` |
| `POST`   | `/all/execute`                   | Run a batch of replace, update, and delete operations in one call.                                                     | `service-catalog-config:Update` |

### Parameters[​](#parameters "Direct link to Parameters")

| Parameter     | In            | Description                                                                                                                                                                                                                                                                   |
| ------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_type` | path          | The entity kind: `ENTITY_TYPE_SERVICE` or `ENTITY_TYPE_DATABASE`. On the list endpoint, pass it as a query parameter (`?entity_type=…`) to filter, or omit it to list every type.                                                                                             |
| `name`        | path          | The entity's name as it appears in the catalog, for example `checkout-service`.                                                                                                                                                                                               |
| `system`      | query or body | Required for **database** entities to address them fully: the database system, for example `postgresql`. Not used for services. Pass it as a query parameter on `GET` and `DELETE`, and as a top-level field in the request body (alongside `metadata`) on `PUT` and `PATCH`. |

## The metadata object[​](#the-metadata-object "Direct link to The metadata object")

Write requests carry a `metadata` object. Every field is optional and independent:

| Field                | Type   | Description                                                                                                                          |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `owner`              | string | Human-readable owner, for example a team name. Up to 100 characters.                                                                 |
| `vcs`                | object | The linked version control repository.                                                                                               |
| `vcs.provider`       | enum   | The VCS host. Currently `VCS_PROVIDER_GITHUB`.                                                                                       |
| `vcs.org`            | string | Organization or user that owns the repository.                                                                                       |
| `vcs.repo`           | string | Repository name.                                                                                                                     |
| `vcs.path`           | string | Optional path within the repository, for monorepos (for example `services/checkout`).                                                |
| `annotations.values` | map    | Free-form string key/value pairs: up to 64 entries, each value up to 4,096 characters, and up to 8 KB in total (the serialized map). |

Responses return the full resource, which adds read-only fields:

| Field                      | Description                                                                                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entityType`, `name`       | The entity this metadata belongs to.                                                                                                                                                |
| `ownerSource`              | How `owner` was set: `OWNER_SOURCE_USER` (set through this API) or `OWNER_SOURCE_CODEOWNERS` (auto-detected). Setting `owner` through this API always makes it `OWNER_SOURCE_USER`. |
| `createTime`, `updateTime` | When the metadata was first created and last changed.                                                                                                                               |

## Replace vs. update[​](#replace-vs-update "Direct link to Replace vs. update")

The two write methods differ in how they treat fields you don't send:

* **Replace** (`PUT`) stores the metadata exactly as sent. Any field you omit is **cleared**, and `annotations` replaces the whole map. It creates the metadata (`201`) if the entity has none yet, or replaces it (`200`) if it does.
* **Update** (`PATCH`) changes only what you send and leaves the rest untouched. `owner` and `vcs` overwrite; `annotations.values` are **merged by key** - send a key to upsert it, send an empty-string value to delete that key, omit a key to leave it, or send an empty map to clear all annotations. It fails with `404` if the entity has no metadata yet; use replace to create it.

## Examples[​](#examples "Direct link to Examples")

### Replace an entity's metadata[​](#replace-an-entitys-metadata "Direct link to Replace an entity's metadata")

```
curl -X PUT "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/ENTITY_TYPE_SERVICE/entities/checkout-service" \

  -H "Authorization: Bearer <cx_api_key>" \

  -H "Content-Type: application/json" \

  -d '{

    "metadata": {

      "owner": "coralogix/payments-squad",

      "vcs": {

        "provider": "VCS_PROVIDER_GITHUB",

        "org": "coralogix",

        "repo": "checkout-service",

        "path": "services/checkout"

      },

      "annotations": { "values": { "team-slack-channel": "#checkout-oncall" } }

    }

  }'
```

Response:

```
{

  "entityMetadata": {

    "entityType": "ENTITY_TYPE_SERVICE",

    "name": "checkout-service",

    "metadata": {

      "owner": "coralogix/payments-squad",

      "vcs": { "provider": "VCS_PROVIDER_GITHUB", "org": "coralogix", "repo": "checkout-service" }

    },

    "ownerSource": "OWNER_SOURCE_USER",

    "createTime": "2026-06-30T12:30:00Z",

    "updateTime": "2026-06-30T12:30:00Z"

  }

}
```

### Update only the owner[​](#update-only-the-owner "Direct link to Update only the owner")

```
curl -X PATCH "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/ENTITY_TYPE_SERVICE/entities/checkout-service" \

  -H "Authorization: Bearer <cx_api_key>" \

  -H "Content-Type: application/json" \

  -d '{ "metadata": { "owner": "coralogix/checkout-squad" } }'
```

To delete a single annotation key, send it with an empty-string value:

```
  -d '{ "metadata": { "annotations": { "values": { "team-slack-channel": "" } } } }'
```

### Get one entity's metadata[​](#get-one-entitys-metadata "Direct link to Get one entity's metadata")

```
curl "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/ENTITY_TYPE_SERVICE/entities/checkout-service" \

  -H "Authorization: Bearer <cx_api_key>"
```

For a database, address it with its system:

```
curl "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/ENTITY_TYPE_DATABASE/entities/orders-db?system=postgresql" \

  -H "Authorization: Bearer <cx_api_key>"
```

### List metadata for an entity type[​](#list-metadata-for-an-entity-type "Direct link to List metadata for an entity type")

```
curl "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2?entity_type=ENTITY_TYPE_SERVICE" \

  -H "Authorization: Bearer <cx_api_key>"
```

### Delete an entity's metadata[​](#delete-an-entitys-metadata "Direct link to Delete an entity's metadata")

```
curl -X DELETE "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/ENTITY_TYPE_SERVICE/entities/checkout-service" \

  -H "Authorization: Bearer <cx_api_key>"
```

### Batch multiple operations[​](#batch-multiple-operations "Direct link to Batch multiple operations")

`POST /all/execute` runs replace, update, and delete operations **in request order**. It is **not atomic**: each successful item is committed immediately, and processing **stops at the first failure**. The response's `matchingResponses` is the succeeded prefix - `matchingResponses[i]` is the result of `requests[i]` - so on failure, retry only from `matchingResponses.length` onward and don't resend the items that already succeeded. A batch holds up to 1,000 operations.

```
curl -X POST "https://api.eu2.coralogix.com:443/service-catalog/entity-metadata/v2/all/execute" \

  -H "Authorization: Bearer <cx_api_key>" \

  -H "Content-Type: application/json" \

  -d '{

    "requests": [

      { "replace": { "entityType": "ENTITY_TYPE_SERVICE", "name": "checkout-service", "metadata": { "owner": "coralogix/payments-squad" } } },

      { "update":  { "entityType": "ENTITY_TYPE_SERVICE", "name": "cart-service", "metadata": { "owner": "coralogix/cart-squad" } } },

      { "delete":  { "entityType": "ENTITY_TYPE_SERVICE", "name": "legacy-service" } }

    ]

  }'
```

## Related resources[​](#related-resources "Direct link to Related resources")

* [Services](https://coralogix.com/docs/user-guides/apm-v2/services.md) and [Databases](https://coralogix.com/docs/user-guides/apm-v2/databases.md) in APM
* [Managing your API keys](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md)