---
title: cURL Version Tags
description: You can add version tags in Coralogix per Application and Subsystem using cURL
url: https://coralogix.com/docs/developer-portal/apis/version-tags/curl-version-tags/
product: cicd
feature: Version Tags
feature_id: version-tags
feature_identifier: cicd/version-tags
last_updated: '2026-11-11'
---

# cURL Version Tags

Set up cURL Version Tags with Coralogix.

## Setup

You can add version tags per application and subsystem using cURL:

**URL:** Choose the <!-- -->https\://api./api/v1/external/tags<!-- --> 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.

**API Key:** To use this API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md) a personal or team API key. It's recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

| Preset          | Action                                                                                                    | Description                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| CICDIntegration | `VERSION-BENCHMARK-TAGS:READ`<br />`VERSION-BENCHMARKS-REPORTS:READ`<br />`VERSION-BENCHMARK-TAGS:UPDATE` | View Version Benchmark Tags<br />View Version Benchmark Reports<br />Modify Version Benchmark Tags |

**Method:** POST

**Body Schema:**

```
{"iconUrl": string,"name": string,"timestamp": date type (JavaScript date string or epoch milliseconds)"application": string[]"subsystem": string[]}
```

**Application:** Your Application name.

**Subsystem:** Your Subsystem(s) name(s). You can input more than one subsystem name, use comma delimiter ‘,’ between Subsystem names.

**Name:** Your Version Tag name.

**Timestamp:** Tag Timestamp. (This is **OPTIONAL**: If a timestamp is not supplied, the current timestamp will be applied).

**IconUrl:** Tag's Picture. (This is **OPTIONAL**: Use an URL *(URL encoded)* to a valid image file uploaded to a public repository)

**Supported Image Formats:** png, jpeg, SVG.

**Maximum File Size:** 50 Kilobytes.

**Note:** If the URL to the image contains spaces, please use *%20*.

For example:

`https://www.myimagesite.com/Path%20To%20The%20Image.png`

**Example (GET):**

```
curl --location --request GET 'https://api.eu2.coralogix.com/api/v1/external/tags/add?key=&application=Application_Name,Application_Name2&subsystem=Subsystem1,Subsystem2,Subsystem3&name=MyFirstTag&timestamp=2020-06-23:09:00:00&iconUrl=your_icon_url'
```

**Example (POST):**

```
curl --location --request POST 'https://api.eu2.coralogix.com/api/v1/external/tags' \

--header 'Authorization: Bearer <cx_api_key>' \

--header 'Content-Type: application/json' \

--data-raw '{

"timestamp": 1617793927675,

"name": "test tag",

"application": ["prd", "dev"],

"subsystem": ["app", "mobile"],

"iconUrl": "my-avatar.png"

}'
```

**Note:** application and subsystem should always be contained between square brackets, even if it is an array of one element, for example:

`"application": ["prd"]`,<br />`"subsystem": ["app"]`

## Send deployment events

Send a deployment to the Coralogix ops events API as well, and it appears as an [event marker](https://coralogix.com/docs/user-guides/apm/features/event-markers.md) on your APM charts, so you can line a latency or error-rate change up with the deployment that caused it. Use this from any pipeline that can run `curl`.

### What you need

* A **Send Your Data** [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md#create-an-api-key) with the **OpsEvents** role preset. The ops events API rejects any other key type or preset, including the `CICDIntegration` key used for version tags, with `403 Forbidden`.
* The ops events endpoint for your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md). Use the domain selector at the top of this page to resolve it:
  <!-- -->
  https\://ingress./v1/ops-events
* The service name and environment exactly as they appear in APM. They must equal the `service.name` and `deployment.environment.name` resource attributes your service reports. An event that matches no service is still stored, but appears only under **All events**.

### Send the event

For a deployment, send a `cdEvent` with `system` set to the matching `CD_SYSTEM_*` value: `CD_SYSTEM_GITHUB`, `CD_SYSTEM_ARGOCD`, `CD_SYSTEM_JENKINS`, `CD_SYSTEM_GITLAB`, `CD_SYSTEM_BITBUCKET`, `CD_SYSTEM_AZURE_DEVOPS`, or `CD_SYSTEM_SPINNAKER`. `cdEvent.system` and `cdEvent.pipeline.name` are required.

```
curl -sS --fail-with-body -X POST 'https://ingress.eu2.coralogix.com/v1/ops-events' \

  -H "Authorization: Bearer $CX_API_KEY" \

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

  --data-binary @- <<EOF

{

  "opsEvent": {

    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",

    "description": "payments-api v2.14.0 deployed to production",

    "attributes": {

      "service": { "name": "payments-api" },

      "environment": "production"

    },

    "cdEvent": {

      "system": "CD_SYSTEM_JENKINS",

      "pipeline": {

        "name": "deploy-production",

        "run": { "id": "1287", "url": "https://jenkins.example.com/job/deploy-production/1287/" },

        "result": { "status": "PIPELINE_RESULT_STATUS_SUCCESS" }

      },

      "vcs": {

        "system": "VCS_SYSTEM_GITHUB",

        "type": "VCS_REF_TYPE_BRANCH",

        "repository": { "name": "org/payments-api", "url": "https://github.com/org/payments-api" },

        "ref": { "head": { "name": "main", "revision": "abc123def456789abcdef0123456789abcdef01" } }

      }

    }

  }

}

EOF
```

Send a `customEvent` for a deployment from a CI/CD system that has no `CD_SYSTEM_*` value, or for an event that isn't a deployment, such as an incident, feature-flag change, or campaign. Carry any details in `attributes.additional`. The marker appears in the **Custom events** group on your charts.

```
curl -sS --fail-with-body -X POST 'https://ingress.eu2.coralogix.com/v1/ops-events' \

  -H "Authorization: Bearer $CX_API_KEY" \

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

  --data-binary @- <<EOF

{

  "opsEvent": {

    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",

    "description": "payments-api v2.14.0 deployed to production",

    "attributes": {

      "service": { "name": "payments-api" },

      "environment": "production",

      "additional": {

        "cdSystem": "my-ci",

        "pipeline": { "name": "deploy-production", "run": { "id": "1287" } }

      }

    },

    "customEvent": {}

  }

}

EOF
```

A successful request returns the server-generated event `id`. The marker then appears on the service's APM charts; see [Event markers](https://coralogix.com/docs/user-guides/apm/features/event-markers.md) for how to show it and for the full field reference. The API rejects a `timestamp` more than 24 hours from the time the request is received, so send the event from the pipeline as it runs rather than backfilling.

## Additional resources

|                     |                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------- |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints.md) |