Scorecards

Use these operations to interact with Scorecards in Cortex.

Required permissions

• Create, read, update, or delete Scorecards: Your API key must have the Edit Scorecards permission.

• View Scorecards: Your API key must have the View Scorecards permission.

• Approve or revoke Scorecard exemptions: Your API key must have the Configure Scorecard exemptions permission.

Operations

List Scorecards

get

Returns scorecards matching optional search criteria. If search criteria is specified we will use search logic, which will not find Scorecards that have yet to be evaluated

Authorizations

bearerAuth

Query parameters

showDraftsbooleanOptional

groupsstring[]Optional

Filter based on groups, which correspond to the x-cortex-groups field in the Catalog Descriptor. Accepts a comma-delimited list of groups

entitiesany[]Optional

Filter based on entity (either tags or CIDs). Accepts a comma-delimited list of entity tag or CIDs, please use only one type of identifier

teamsany[]Optional

Filter based on team (either tags or CIDs). Accepts a comma-delimited list of team tag or CIDs, please use only one type of identifier

pageinteger · int32Required

Page number to return, 0-indexed. Default 0.

Default: 0

pageSizeinteger · int32Required

Number of results to return per page, between 1 and 1000. Default 250.

Default: 250

Responses

200

OK

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "page": 1,
  "scorecards": [
    {
      "description": "text",
      "evaluation": {
        "window": 4
      },
      "exemptions": {
        "autoApprove": false,
        "enabled": true
      },
      "filter": {
        "groups": {
          "exclude": [
            "text"
          ],
          "include": [
            "text"
          ]
        },
        "query": "text",
        "types": {
          "exclude": [
            "text"
          ],
          "include": [
            "text"
          ]
        }
      },
      "isDraft": true,
      "lastUpdated": "2025-09-13T13:07:02.401Z",
      "levels": [
        {
          "level": {
            "name": "Bronze",
            "number": 1
          }
        }
      ],
      "name": "Production Readiness Scorecard",
      "notifications": {
        "enabled": true,
        "scoreDropNotificationsEnabled": true
      },
      "rules": [
        {
          "description": "This rule is very important because you must pass it",
          "effectiveFrom": "2024-01-01T00:00:00Z",
          "expression": "custom(\"key\") = \"value\"",
          "failureMessage": "To fix this rule, visit [our internal doc][docs.cortex.io]",
          "filter": {
            "groups": {
              "exclude": [
                "text"
              ],
              "include": [
                "text"
              ]
            },
            "query": "text",
            "types": {
              "exclude": [
                "text"
              ],
              "include": [
                "text"
              ]
            }
          },
          "identifier": "96db03f1-2529-3fc3-9f13-7fb4dd28f427",
          "levelName": "text",
          "title": "Key value must be correct",
          "weight": 1
        }
      ],
      "tag": "production-readiness-scorecard"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Retrieve Scorecard scores

get

Returns latest scores for all entities in the Scorecard

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

Query parameters

entityTagstringOptional

Entity tag (x-cortex-tag)

pageSizeinteger · int32Required

Number of results to return per page, between 1 and 1000. Default 250.

Default: 250

pageinteger · int32Required

Page number to return, 0-indexed. Default 0.

Default: 0

Responses

200

Scorecard scores

application/json

404

Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag}/scores HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "scorecardFilter": {
    "groups": {
      "exclude": [
        "text"
      ],
      "include": [
        "text"
      ]
    },
    "query": "text",
    "types": {
      "exclude": [
        "text"
      ],
      "include": [
        "text"
      ]
    }
  },
  "scorecardName": "text",
  "scorecardTag": "text",
  "serviceScores": [
    {
      "lastEvaluated": "2025-09-13T13:07:02.401Z",
      "ruleExemptions": [
        {
          "endDate": "2025-09-13T13:07:02.401Z",
          "exemptionStatus": {
            "date": "2025-09-13T13:07:02.401Z",
            "handledBy": "[Circular Reference]",
            "status": "text"
          },
          "requestedBy": {
            "0": "[",
            "1": "C",
            "2": "i",
            "3": "r",
            "4": "c",
            "5": "u",
            "6": "l",
            "7": "a",
            "8": "r",
            "9": " ",
            "10": "R",
            "11": "e",
            "12": "f",
            "13": "e",
            "14": "r",
            "15": "e",
            "16": "n",
            "17": "c",
            "18": "e",
            "19": "]",
            "type": "text"
          },
          "requestedDate": "2025-09-13T13:07:02.401Z",
          "requestingReason": "text",
          "ruleExpression": "text",
          "ruleIdentifier": "text"
        }
      ],
      "score": {
        "ladderLevels": [
          {
            "level": {
              "name": "Bronze",
              "number": 1
            }
          }
        ],
        "rules": [
          {
            "error": "text",
            "expression": "text",
            "identifier": "text",
            "score": 1
          }
        ],
        "summary": {
          "percentage": 1,
          "score": 1,
          "totalPossibleScore": 1
        }
      },
      "service": {
        "groups": [
          "text"
        ],
        "id": "en2da8159dbeefb974",
        "name": "My Favorite Entity",
        "owners": {
          "groups": [
            "text"
          ],
          "individuals": [
            {
              "description": "text",
              "email": "text"
            }
          ]
        },
        "tag": "my-favorite-entity"
      }
    }
  ]
}

Retrieve entity Scorecard scores

get

Authorizations

bearerAuth

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

All entity Scorecard scores

application/json

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/catalog/{tagOrId}/scorecards HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

[
  {
    "ladderLevels": [
      {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      }
    ],
    "score": 1,
    "scorePercentage": 1,
    "scorecardName": "text",
    "totalPossibleScore": 1
  }
]

Retrieve Scorecard

get

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

Responses

200

Successfully retrieved Scorecard

application/json

404

Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "scorecard": {
    "description": "text",
    "evaluation": {
      "window": 4
    },
    "exemptions": {
      "autoApprove": false,
      "enabled": true
    },
    "filter": {
      "groups": {
        "exclude": [
          "text"
        ],
        "include": [
          "text"
        ]
      },
      "query": "text",
      "types": {
        "exclude": [
          "text"
        ],
        "include": [
          "text"
        ]
      }
    },
    "isDraft": true,
    "lastUpdated": "2025-09-13T13:07:02.401Z",
    "levels": [
      {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      }
    ],
    "name": "Production Readiness Scorecard",
    "notifications": {
      "enabled": true,
      "scoreDropNotificationsEnabled": true
    },
    "rules": [
      {
        "description": "This rule is very important because you must pass it",
        "effectiveFrom": "2024-01-01T00:00:00Z",
        "expression": "custom(\"key\") = \"value\"",
        "failureMessage": "To fix this rule, visit [our internal doc][docs.cortex.io]",
        "filter": {
          "groups": {
            "exclude": [
              "text"
            ],
            "include": [
              "text"
            ]
          },
          "query": "text",
          "types": {
            "exclude": [
              "text"
            ],
            "include": [
              "text"
            ]
          }
        },
        "identifier": "96db03f1-2529-3fc3-9f13-7fb4dd28f427",
        "levelName": "text",
        "title": "Key value must be correct",
        "weight": 1
      }
    ],
    "tag": "production-readiness-scorecard"
  }
}

Retrieve Scorecard descriptor

get

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

Responses

200

Successfully retrieved Scorecard descriptor

application/json

Responsestring

404

Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag}/descriptor HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

text

Retrieve Scorecard shields.io badge

get

Authorizations

bearerAuth

Path parameters

scorecardTagstringRequired

Unique tag for the Scorecard.

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

Shields.io badge

application/json

404

Entity or Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{scorecardTag}/entity/{tagOrId}/badge HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "value": "text"
}

Retrieve next steps for entity in Scorecard

get

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

Query parameters

entityTagstringRequired

The entity tag (x-cortex-tag) that identifies the entity.

Responses

200

Any rules remaining for the entity to reach the next level in the Scorecard.

application/json

404

Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag}/next-steps HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "nextSteps": [
    {
      "currentLevel": {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      },
      "nextLevel": {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      },
      "rulesToComplete": [
        {
          "description": "text",
          "expression": "text",
          "identifier": "text",
          "title": "text"
        }
      ]
    }
  ]
}

Create or update Scorecard

post

Create or update a Scorecard using the descriptor YAML. The operation is determined by the existence of a Scorecard with the same tag as passed in the descriptor.

Authorizations

bearerAuth

Query parameters

dryRunbooleanOptional

When true, this endpoint only validates the descriptor contents and returns any errors or warnings.

Body

application/yaml;charset=UTF-8

anyOptional

Responses

200

Created Scorecard

application/json

400

Bad Request

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

post

HTTPcURLJavaScriptPython

POST /api/v1/scorecards/descriptor HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/yaml;charset=UTF-8
Accept: */*

{
  "scorecard": {
    "description": "text",
    "evaluation": {
      "window": 4
    },
    "exemptions": {
      "autoApprove": false,
      "enabled": true
    },
    "filter": {
      "groups": {
        "exclude": [
          "text"
        ],
        "include": [
          "text"
        ]
      },
      "query": "text",
      "types": {
        "exclude": [
          "text"
        ],
        "include": [
          "text"
        ]
      }
    },
    "isDraft": true,
    "lastUpdated": "2025-09-13T13:07:02.401Z",
    "levels": [
      {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      }
    ],
    "name": "Production Readiness Scorecard",
    "notifications": {
      "enabled": true,
      "scoreDropNotificationsEnabled": true
    },
    "rules": [
      {
        "description": "This rule is very important because you must pass it",
        "effectiveFrom": "2024-01-01T00:00:00Z",
        "expression": "custom(\"key\") = \"value\"",
        "failureMessage": "To fix this rule, visit [our internal doc][docs.cortex.io]",
        "filter": {
          "groups": {
            "exclude": [
              "text"
            ],
            "include": [
              "text"
            ]
          },
          "query": "text",
          "types": {
            "exclude": [
              "text"
            ],
            "include": [
              "text"
            ]
          }
        },
        "identifier": "96db03f1-2529-3fc3-9f13-7fb4dd28f427",
        "levelName": "text",
        "title": "Key value must be correct",
        "weight": 1
      }
    ],
    "tag": "production-readiness-scorecard"
  }
}

Request Scorecard rule exemption

post

Request Scorecard rule exemption

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

entityTagstringRequired

The entity tag (x-cortex-tag) that identifies the entity.

Body

application/json

daysinteger · int64 | nullableOptional

Number of days how long rule should be exempt. If not set, rule will be exempt until exempt until revoked.

reasonstringRequired

Reason for creating exemption

ruleIdentifierstringRequired

Identifier of the Scorecard rule to request exemption for

Responses

200

Successfully requested Scorecard rule exemption

application/json

404

Scorecard not found, entity not found, or rule with given identifier not found within the Scorecard

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

post

HTTPcURLJavaScriptPython

POST /api/v1/scorecards/{tag}/entity/{entityTag}/exemption HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "days": 1,
  "reason": "text",
  "ruleIdentifier": "text"
}

{
  "endDate": "2025-09-13T13:07:02.401Z",
  "exemptionStatus": {
    "date": "2025-09-13T13:07:02.401Z",
    "handledBy": {
      "0": "[",
      "1": "C",
      "2": "i",
      "3": "r",
      "4": "c",
      "5": "u",
      "6": "l",
      "7": "a",
      "8": "r",
      "9": " ",
      "10": "R",
      "11": "e",
      "12": "f",
      "13": "e",
      "14": "r",
      "15": "e",
      "16": "n",
      "17": "c",
      "18": "e",
      "19": "]",
      "type": "text",
      "email": "text",
      "name": "text"
    },
    "status": "text"
  },
  "requestedBy": {
    "0": "[",
    "1": "C",
    "2": "i",
    "3": "r",
    "4": "c",
    "5": "u",
    "6": "l",
    "7": "a",
    "8": "r",
    "9": " ",
    "10": "R",
    "11": "e",
    "12": "f",
    "13": "e",
    "14": "r",
    "15": "e",
    "16": "n",
    "17": "c",
    "18": "e",
    "19": "]",
    "type": "text",
    "email": "text",
    "name": "text"
  },
  "requestedDate": "2025-09-13T13:07:02.401Z",
  "requestingReason": "text"
}

Revoke Scorecard rule exemption

put

Revoke Scorecard rule exemption

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

entityTagstringRequired

The entity tag (x-cortex-tag) that identifies the entity.

Body

application/json

reasonstringRequired

ruleIdentifierstringRequired

Identifier of the Scorecard rule

Responses

200

Revoked Scorecard rule exemptions

application/json

400

No approved exemptions to revoke found

application/json

404

Scorecard not found, entity not found, or rule with given identifier not found within the Scorecard

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put

HTTPcURLJavaScriptPython

PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/revoke HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "reason": "text",
  "ruleIdentifier": "text"
}

{
  "exemptions": [
    {
      "endDate": "2025-09-13T13:07:02.401Z",
      "exemptionStatus": {
        "date": "2025-09-13T13:07:02.401Z",
        "handledBy": {
          "0": "[",
          "1": "C",
          "2": "i",
          "3": "r",
          "4": "c",
          "5": "u",
          "6": "l",
          "7": "a",
          "8": "r",
          "9": " ",
          "10": "R",
          "11": "e",
          "12": "f",
          "13": "e",
          "14": "r",
          "15": "e",
          "16": "n",
          "17": "c",
          "18": "e",
          "19": "]",
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "0": "[",
        "1": "C",
        "2": "i",
        "3": "r",
        "4": "c",
        "5": "u",
        "6": "l",
        "7": "a",
        "8": "r",
        "9": " ",
        "10": "R",
        "11": "e",
        "12": "f",
        "13": "e",
        "14": "r",
        "15": "e",
        "16": "n",
        "17": "c",
        "18": "e",
        "19": "]",
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-09-13T13:07:02.401Z",
      "requestingReason": "text"
    }
  ]
}

Approve Scorecard rule exemption

put

Approve Scorecard rule exemption

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

entityTagstringRequired

The entity tag (x-cortex-tag) that identifies the entity.

Body

application/json

ruleIdentifierstringRequired

Identifier of the Scorecard rule

Responses

200

Successfully approved Scorecard rule exemptions

application/json

400

No pending exemptions to approve found

application/json

404

Scorecard not found, entity not found, or rule with given identifier not found within the Scorecard

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put

HTTPcURLJavaScriptPython

PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/approve HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "ruleIdentifier": "text"
}

{
  "exemptions": [
    {
      "endDate": "2025-09-13T13:07:02.401Z",
      "exemptionStatus": {
        "date": "2025-09-13T13:07:02.401Z",
        "handledBy": {
          "0": "[",
          "1": "C",
          "2": "i",
          "3": "r",
          "4": "c",
          "5": "u",
          "6": "l",
          "7": "a",
          "8": "r",
          "9": " ",
          "10": "R",
          "11": "e",
          "12": "f",
          "13": "e",
          "14": "r",
          "15": "e",
          "16": "n",
          "17": "c",
          "18": "e",
          "19": "]",
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "0": "[",
        "1": "C",
        "2": "i",
        "3": "r",
        "4": "c",
        "5": "u",
        "6": "l",
        "7": "a",
        "8": "r",
        "9": " ",
        "10": "R",
        "11": "e",
        "12": "f",
        "13": "e",
        "14": "r",
        "15": "e",
        "16": "n",
        "17": "c",
        "18": "e",
        "19": "]",
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-09-13T13:07:02.401Z",
      "requestingReason": "text"
    }
  ]
}

Deny Scorecard rule exemption

put

Deny Scorecard rule exemption

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

entityTagstringRequired

The entity tag (x-cortex-tag) that identifies the entity.

Body

application/json

reasonstringRequired

ruleIdentifierstringRequired

Identifier of the Scorecard rule

Responses

200

Denied Scorecard rule exemptions

application/json

400

No pending exemptions to approve found

application/json

404

Scorecard not found, entity not found, or rule with given identifier not found within the Scorecard

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put

HTTPcURLJavaScriptPython

PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/deny HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "reason": "text",
  "ruleIdentifier": "text"
}

{
  "exemptions": [
    {
      "endDate": "2025-09-13T13:07:02.401Z",
      "exemptionStatus": {
        "date": "2025-09-13T13:07:02.401Z",
        "handledBy": {
          "0": "[",
          "1": "C",
          "2": "i",
          "3": "r",
          "4": "c",
          "5": "u",
          "6": "l",
          "7": "a",
          "8": "r",
          "9": " ",
          "10": "R",
          "11": "e",
          "12": "f",
          "13": "e",
          "14": "r",
          "15": "e",
          "16": "n",
          "17": "c",
          "18": "e",
          "19": "]",
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "0": "[",
        "1": "C",
        "2": "i",
        "3": "r",
        "4": "c",
        "5": "u",
        "6": "l",
        "7": "a",
        "8": "r",
        "9": " ",
        "10": "R",
        "11": "e",
        "12": "f",
        "13": "e",
        "14": "r",
        "15": "e",
        "16": "n",
        "17": "c",
        "18": "e",
        "19": "]",
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-09-13T13:07:02.401Z",
      "requestingReason": "text"
    }
  ]
}

Delete Scorecard

delete

Authorizations

bearerAuth

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

Responses

200

Successfully deleted Scorecard

No content

404

Scorecard not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

delete

HTTPcURLJavaScriptPython

DELETE /api/v1/scorecards/{tag} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

No content