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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

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

/api/v1/scorecards

HTTPcURLJavaScriptPython

GET /api/v1/scorecards?page=0&pageSize=250 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
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-12-29T03:32:41.490Z",
      "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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/scores

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag}/scores?pageSize=250&page=0 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "scorecardFilter": {
    "groups": {
      "exclude": [
        "text"
      ],
      "include": [
        "text"
      ]
    },
    "query": "text",
    "types": {
      "exclude": [
        "text"
      ],
      "include": [
        "text"
      ]
    }
  },
  "scorecardId": 1,
  "scorecardName": "text",
  "scorecardTag": "text",
  "serviceScores": [
    {
      "lastEvaluated": "2025-12-29T03:32:41.490Z",
      "ruleExemptions": [
        {
          "endDate": "2025-12-29T03:32:41.490Z",
          "exemptionStatus": {
            "date": "2025-12-29T03:32:41.490Z",
            "handledBy": "[Circular Reference]",
            "status": "text"
          },
          "requestedBy": {
            "type": "text",
            "email": "text",
            "name": "text"
          },
          "requestedDate": "2025-12-29T03:32:41.490Z",
          "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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/catalog/{tagOrId}/scorecards

HTTPcURLJavaScriptPython

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

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

Retrieve Scorecard

get

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
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-12-29T03:32:41.490Z",
    "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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/descriptor

HTTPcURLJavaScriptPython

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

text

Retrieve Scorecard shields.io badge

get

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{scorecardTag}/entity/{tagOrId}/badge

HTTPcURLJavaScriptPython

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

{
  "value": "text"
}

Retrieve next steps for entity in Scorecard

get

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/next-steps

HTTPcURLJavaScriptPython

GET /api/v1/scorecards/{tag}/next-steps?entityTag=text HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/descriptor

HTTPcURLJavaScriptPython

POST /api/v1/scorecards/descriptor HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
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-12-29T03:32:41.490Z",
    "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

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/entity/{entityTag}/exemption

HTTPcURLJavaScriptPython

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

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

{
  "endDate": "2025-12-29T03:32:41.490Z",
  "exemptionStatus": {
    "date": "2025-12-29T03:32:41.490Z",
    "handledBy": {
      "type": "text",
      "email": "text",
      "name": "text"
    },
    "status": "text"
  },
  "requestedBy": {
    "type": "text",
    "email": "text",
    "name": "text"
  },
  "requestedDate": "2025-12-29T03:32:41.490Z",
  "requestingReason": "text"
}

Evaluate entity scorecard score

post

Triggers score evaluation for entity scorecard

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Path parameters

tagstringRequired

Unique tag for the Scorecard

Example: my-production-readiness-checklist

entityTagstringRequired

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

Responses

200

Scorecard score evaluation triggered successfully

No content

403

Unauthorized

404

Scorecard not found

409

Already evaluating scorecard

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

500

Scorecard evaluation failed

post

/api/v1/scorecards/{tag}/entity/{entityTag}/scores

HTTPcURLJavaScriptPython

POST /api/v1/scorecards/{tag}/entity/{entityTag}/scores HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Revoke Scorecard rule exemption

put

Revoke Scorecard rule exemption

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/entity/{entityTag}/exemption/revoke

HTTPcURLJavaScriptPython

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

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

{
  "exemptions": [
    {
      "endDate": "2025-12-29T03:32:41.490Z",
      "exemptionStatus": {
        "date": "2025-12-29T03:32:41.490Z",
        "handledBy": {
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-12-29T03:32:41.490Z",
      "requestingReason": "text"
    }
  ]
}

Approve Scorecard rule exemption

put

Approve Scorecard rule exemption

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/entity/{entityTag}/exemption/approve

HTTPcURLJavaScriptPython

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

{
  "ruleIdentifier": "text"
}

{
  "exemptions": [
    {
      "endDate": "2025-12-29T03:32:41.490Z",
      "exemptionStatus": {
        "date": "2025-12-29T03:32:41.490Z",
        "handledBy": {
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-12-29T03:32:41.490Z",
      "requestingReason": "text"
    }
  ]
}

Deny Scorecard rule exemption

put

Deny Scorecard rule exemption

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}/entity/{entityTag}/exemption/deny

HTTPcURLJavaScriptPython

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

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

{
  "exemptions": [
    {
      "endDate": "2025-12-29T03:32:41.490Z",
      "exemptionStatus": {
        "date": "2025-12-29T03:32:41.490Z",
        "handledBy": {
          "type": "text",
          "email": "text",
          "name": "text"
        },
        "status": "text"
      },
      "requestedBy": {
        "type": "text",
        "email": "text",
        "name": "text"
      },
      "requestedDate": "2025-12-29T03:32:41.490Z",
      "requestingReason": "text"
    }
  ]
}

Delete Scorecard

delete

Authorizations

bearerAuth

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

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

/api/v1/scorecards/{tag}

HTTPcURLJavaScriptPython

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

No content