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
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
Filter based on groups, which correspond to the x-cortex-groups
field in the Catalog Descriptor. Accepts a comma-delimited list of groups
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
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
Page number to return, 0-indexed. Default 0.
0
Number of results to return per page, between 1 and 1000. Default 250.
250
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-06-28T19:25:29.808Z",
"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
}
Returns latest scores for all entities in the Scorecard
Unique tag for the Scorecard
my-production-readiness-checklist
Entity tag (x-cortex-tag)
Number of results to return per page, between 1 and 1000. Default 250.
250
Page number to return, 0-indexed. Default 0.
0
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-06-28T19:25:29.808Z",
"ruleExemptions": [
{
"endDate": "2025-06-28T19:25:29.808Z",
"exemptionStatus": {
"date": "2025-06-28T19:25:29.808Z",
"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-06-28T19:25:29.808Z",
"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"
}
}
]
}
The tag (x-cortex-tag
) or unique, auto-generated identifier for the entity.
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
}
]
Unique tag for the Scorecard
my-production-readiness-checklist
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-06-28T19:25:29.808Z",
"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"
}
}
Unique tag for the Scorecard
my-production-readiness-checklist
GET /api/v1/scorecards/{tag}/descriptor HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
text
Unique tag for the Scorecard.
The tag (x-cortex-tag
) or unique, auto-generated identifier for the entity.
GET /api/v1/scorecards/{scorecardTag}/entity/{tagOrId}/badge HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"value": "text"
}
Unique tag for the Scorecard
my-production-readiness-checklist
The entity tag (x-cortex-tag
) that identifies the entity.
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 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.
When true, this endpoint only validates the descriptor contents and returns any errors or warnings.
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-06-28T19:25:29.808Z",
"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
Unique tag for the Scorecard
my-production-readiness-checklist
The entity tag (x-cortex-tag
) that identifies the entity.
Number of days how long rule should be exempt. If not set, rule will be exempt until exempt until revoked.
Reason for creating exemption
Identifier of the Scorecard rule to request exemption for
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-06-28T19:25:29.808Z",
"exemptionStatus": {
"date": "2025-06-28T19:25:29.808Z",
"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-06-28T19:25:29.808Z",
"requestingReason": "text"
}
Revoke Scorecard rule exemption
Unique tag for the Scorecard
my-production-readiness-checklist
The entity tag (x-cortex-tag
) that identifies the entity.
Identifier of the Scorecard rule
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-06-28T19:25:29.808Z",
"exemptionStatus": {
"date": "2025-06-28T19:25:29.808Z",
"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-06-28T19:25:29.808Z",
"requestingReason": "text"
}
]
}
Approve Scorecard rule exemption
Unique tag for the Scorecard
my-production-readiness-checklist
The entity tag (x-cortex-tag
) that identifies the entity.
Identifier of the Scorecard rule
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-06-28T19:25:29.808Z",
"exemptionStatus": {
"date": "2025-06-28T19:25:29.808Z",
"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-06-28T19:25:29.808Z",
"requestingReason": "text"
}
]
}
Deny Scorecard rule exemption
Unique tag for the Scorecard
my-production-readiness-checklist
The entity tag (x-cortex-tag
) that identifies the entity.
Identifier of the Scorecard rule
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-06-28T19:25:29.808Z",
"exemptionStatus": {
"date": "2025-06-28T19:25:29.808Z",
"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-06-28T19:25:29.808Z",
"requestingReason": "text"
}
]
}
Unique tag for the Scorecard
my-production-readiness-checklist
DELETE /api/v1/scorecards/{tag} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
No content
Last updated
Was this helpful?