Service Catalog Entity Metadata API

Open in ChatGPTOpen in Claude

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 - 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

• A personal or team API key.
• The service-catalog-config:Read permission for read operations, and service-catalog-config:Update for write operations.

Authentication

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

Authorization: Bearer <cx_api_key>

Endpoint

This API is served from the Coralogix management endpoint. Select the api.eu2.coralogix.com:443 endpoint that corresponds to your Coralogix domain 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

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

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

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

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

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

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

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

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

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

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

• Services and Databases in APM
• Managing your API keys