Skip to content

API

For live use cases where you may want to constantly push data into Cortex, you may use our REST API.

Authentication

To authenticate requests to our API, you'll need to create an API key in settings.

  1. Create an API key on the Cortex dashboard (Settings → API Keys)
  2. Include the token as a Bearer token in the Authorization header for all requests (for example: Authorization: Bearer <token>).

Custom Metadata

Save

You can push data by POSTing to /api/v1/services/tags/{service-identifier}/custom-data , where the service-identifier is the unique tag of the service as seen in the Cortex dashboard.

The request body is the following, in JSON format. For authentication details, see the Updating Cortex section.

Field Type Description
key string The key for custom data
value object (string, boolean, number, list, ...) Value to set for the service
description string (optional) An optional description for the data to be displayed in the dashboard.
force boolean (optional) To overwrite data

Reminder: YAML is the source of truth

If a key is set through the YAML file, an API call will NOT overwrite the existing value. Instead, it will simply return the existing value - you'll notice the source value in the response body is YAML.

To explicitly overwrite values set in the YAML file, use the force flag in the request body. If you find yourself using the force flag, you should likely remove the field from the YAML file since it is no longer the source of truth, or update the value in the cortex.yaml file instead.

curl
  -v
  -d '{ "key": "my-custom-data", "value": { "some": "value" }, "description": "My custom data" }'
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/custom-data"

Delete

You can remove data from the YAML by DELETE-ing to /api/v1/services/tags/{service-identifier}/custom-data?key=mykey, where the service-identifier is the unique tag of the service as seen in the Cortex dashboard.

The query params are the following. For authentication details, see the Updating Cortex section.

Field Type Description
key string The key for custom data
force boolean (optional) To overwrite data

Reminder: YAML is the source of truth

If a key is set through the YAML file, an API call will NOT delete the existing value.

To explicitly delete values set in the YAML file, use the `force` flag in the request body. If you find yourself using the `force`
flag, you should likely remove the field from the YAML file since it is no longer the source of truth, or update the
value in the `cortex.yaml` file instead.
curl
  -v
  -X DELETE
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/custom-data?key=mykey"

Package Versions

Cortex supports pushing package versions to write scorecard rules on top of. With scorecards you can stay on top of package drift and known security vulnerabilities!

If you enable automatic Git repository parsing, we'll process all relevant package versions every merge to master (package-lock.json, Pipfile.lock, etc).

NPM

You can tag your service with pinned NPM versions by uploading your package-lock.json file through the API.

You can upload by POSTing the contents of your package-lock.json to /api/v1/services/tags/{service-identifier}/packages/node/package-lock.

Example:

curl
  -v
  --data-ascii "@package-lock.json"
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/node/package-lock"

Java

There's no convenient way (yet) for us to automatically parse your Java versions, but you can still manually upload services' Java package versions through the API. You can also do a bulk upload of versions with the bulk flag set to true.

curl
-v
-d '{ "name": "my-package", "version": "1.0.1-SNAPSHOT" }'
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <token>"
"https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/java"
curl
-v
-d '[{ "name": "my-package", "version": "1.0.1-SNAPSHOT" }, { "name": "my-second-package", "version": 1.0.0 }]'
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <token>"
"https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/java?bulk=true"

Python

You can tag your service by uploading your pipfile.lock or the requirements.txt file through the API.

curl
  -v
  --data-ascii "@pipfile.lock"
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/python/pipfile"
curl
  -v
  --data-ascii "@requirements.txt"
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/python/requirements"

Go

You can tag your service with pinned Go.sum versions by uploading your go.sum file through the API.

Example:

curl
  -v
  --data-ascii "@go.sum"
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/go/gosum"

.NET (Nuget)

You can bulk upload your Nuget packages through the API.

Example:

curl
-v
-d '[{ "name": "my-package", "version": "1.0.1-SNAPSHOT" }, { "name": "my-second-package", "version": 1.0.0 }]'
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <token>"
"https://api.getcortexapp.com/api/v1/services/tags/my-service/packages/dotnet/nuget?bulk=true"

Deploys

Cortex exposes an API to push deployment data, so you can get a feed of recent deployments through the UI.

You can push data by POSTing to /api/v1/services/tags/{service-identifier}/deploys , where the service-identifier is the unique tag of the service as seen in the Cortex dashboard.

The request body is the following, in JSON format. For authentication details, see the Updating Cortex section.

Field Type Description
title string Title of the deployment.
timestamp ISO-8601 string with timezone Instant of deployment (e.g. "2021-01-26T21:06:03Z").
type string Type of deployment. Must be one of DEPLOY, SCALE, ROLLBACK, RESTART.
sha string (optional) Git SHA of the deployment.
deployer {"name": "string", "email": "string"} (optional) Details about the person who did the deployment. Both name and email are optional.
environment string (optional) Name of environment in which the deployment occurred.
customData {"string" : "string"} (optional) Optional key/value metadata about the deployment.

Example

curl
  -v
  -d '{"title": "My Deploy", "timestamp": "2021-01-26T21:06:03Z", "type": "DEPLOY", "sha": "my-sha", "deployer": {"name": "Nikhil Unni", "email": "nikhil.unni@getcortexapp.com"}, "environment": "prod", "customData": {"my-key": "my-value", "my-other-key": "my-other-value"}}'
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/services/tags/my-service/deploys