List and retrieve Scorecards, fetch scores and next steps, get a per-entity badge, submit scores, and manage a scorecard via its descriptor. Includes the exemption workflow (request, approve, deny, revoke) used to grant entities time-boxed exceptions from a standard.
openapi: 3.0.3
info:
title: Cortex REST API
description: >-
Cortex (cortex.io) is an internal developer portal (IDP) and software catalog.
This OpenAPI describes the documented public REST API at
https://api.getcortexapp.com/api/v1, covering the Catalog/Entities, Scorecards,
Custom Data, Initiatives, Deploys, and third-party Integration configurations
(GitHub shown as the exemplar). All requests are authenticated with an
Authorization Bearer token - an API key created in the Settings page of your
Cortex workspace. Paths and methods here are grounded in the live Cortex API
reference (docs.cortex.io/api); request and response schemas are honestly
modeled and simplified, not copied verbatim, and are marked as such. Verify
exact payloads against the current Cortex documentation.
NOTE - this is Cortex.io the internal developer portal, NOT Cortex XSOAR
(Palo Alto Networks) and NOT Orange Logic's Cortex DAM.
version: '1.0'
contact:
name: Cortex
url: https://www.cortex.io
servers:
- url: https://api.getcortexapp.com/api/v1
description: Cortex REST API
security:
- bearerAuth: []
tags:
- name: Catalog
description: Software catalog entities - services, resources, domains, and custom types.
- name: Scorecards
description: Standards that measure catalog entities, with scores and exemptions.
- name: Custom Data
description: Arbitrary key/value metadata attached to catalog entities.
- name: Initiatives
description: Time-boxed improvement campaigns driving entities toward a Scorecard target.
- name: Deploys
description: Deployment events recorded per catalog entity.
- name: Integrations
description: Third-party integration configurations that hydrate the catalog.
paths:
/catalog:
get:
operationId: listCatalogEntities
tags:
- Catalog
summary: List catalog entities
description: >-
Lists all catalog entities (services, resources, domains, and custom
entity types). Supports pagination via page and pageSize, and filtering by
type, group, and owner.
parameters:
- name: page
in: query
schema:
type: integer
default: 0
- name: pageSize
in: query
schema:
type: integer
default: 250
- name: types
in: query
schema:
type: string
responses:
'200':
description: A page of catalog entities.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityList'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteCatalogEntitiesByType
tags:
- Catalog
summary: Delete entities by type
description: Deletes catalog entities matching the given entity type.
parameters:
- name: type
in: query
schema:
type: string
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/descriptors:
get:
operationId: listEntityDescriptors
tags:
- Catalog
summary: List entity descriptors
description: Lists the entity descriptors (YAML source of truth) for catalog entities.
responses:
'200':
description: A list of entity descriptors.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: getCatalogEntity
tags:
- Catalog
summary: Retrieve entity details
description: Retrieves a single catalog entity by its tag (x-cortex-tag) or id.
responses:
'200':
description: The requested catalog entity.
content:
application/json:
schema:
$ref: '#/components/schemas/Entity'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCatalogEntity
tags:
- Catalog
summary: Delete an entity
description: Deletes a catalog entity by tag or id.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/openapi:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: getEntityDescriptor
tags:
- Catalog
summary: Retrieve entity descriptor
description: Retrieves the entity descriptor (OpenAPI-style YAML/JSON) for a single entity.
responses:
'200':
description: The entity descriptor.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/archive:
parameters:
- $ref: '#/components/parameters/TagOrId'
put:
operationId: archiveEntity
tags:
- Catalog
summary: Archive an entity
description: Archives a catalog entity, hiding it from active views while retaining history.
responses:
'200':
description: The archived entity.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/unarchive:
parameters:
- $ref: '#/components/parameters/TagOrId'
put:
operationId: unarchiveEntity
tags:
- Catalog
summary: Unarchive an entity
description: Restores a previously archived catalog entity.
responses:
'200':
description: The restored entity.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/gitops-logs:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: getGitopsLogs
tags:
- Catalog
summary: Retrieve GitOps logs
description: Retrieves the GitOps ingestion log for an entity descriptor.
responses:
'200':
description: GitOps log entries.
'401':
$ref: '#/components/responses/Unauthorized'
/open-api:
post:
operationId: upsertEntity
tags:
- Catalog
summary: Create or update an entity (upsert)
description: >-
Creates or updates a catalog entity from an entity descriptor. Behaves as
an upsert by default. Accepts application/openapi+yaml or JSON.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EntityDescriptor'
responses:
'200':
description: The created or updated entity.
content:
application/json:
schema:
$ref: '#/components/schemas/Entity'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: patchEntity
tags:
- Catalog
summary: Create or patch an entity (merge)
description: Merges the supplied descriptor changes into an existing entity.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EntityDescriptor'
responses:
'200':
description: The patched entity.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/scorecards:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: getEntityScorecardScores
tags:
- Scorecards
summary: Retrieve scorecard scores for an entity
description: >-
Retrieves the scores an entity has earned across the Scorecards it is
evaluated against, including ladder level, score, and score percentage.
responses:
'200':
description: Scorecard scores for the entity.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityScorecardScores'
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards:
get:
operationId: listScorecards
tags:
- Scorecards
summary: List scorecards
description: Lists all Scorecards defined in the workspace.
responses:
'200':
description: A list of scorecards.
content:
application/json:
schema:
$ref: '#/components/schemas/ScorecardList'
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/descriptor:
post:
operationId: upsertScorecardDescriptor
tags:
- Scorecards
summary: Create or update a scorecard
description: Creates or updates a Scorecard from its descriptor (YAML/JSON).
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The created or updated scorecard.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
get:
operationId: getScorecard
tags:
- Scorecards
summary: Retrieve a scorecard
description: Retrieves a single Scorecard by its tag.
responses:
'200':
description: The requested scorecard.
content:
application/json:
schema:
$ref: '#/components/schemas/Scorecard'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteScorecard
tags:
- Scorecards
summary: Delete a scorecard
description: Deletes a Scorecard by tag.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}/descriptor:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
get:
operationId: getScorecardDescriptor
tags:
- Scorecards
summary: Retrieve a scorecard descriptor
description: Retrieves the descriptor (source-of-truth definition) for a Scorecard.
responses:
'200':
description: The scorecard descriptor.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}/scores:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
get:
operationId: getScorecardScores
tags:
- Scorecards
summary: Retrieve scores for a scorecard
description: Retrieves the scores of every entity evaluated against a Scorecard.
responses:
'200':
description: Scores across entities.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}/next-steps:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
get:
operationId: getScorecardNextSteps
tags:
- Scorecards
summary: Retrieve next steps for a scorecard
description: Retrieves the recommended next steps to improve scores on a Scorecard.
responses:
'200':
description: Next steps.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{scorecardTag}/entity/{tagOrId}/badge:
parameters:
- name: scorecardTag
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TagOrId'
get:
operationId: getScorecardBadge
tags:
- Scorecards
summary: Retrieve a scorecard badge for an entity
description: Retrieves an SVG/JSON badge representing an entity's standing on a Scorecard.
responses:
'200':
description: The badge.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}/entity/{entityTag}/scores:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
- name: entityTag
in: path
required: true
schema:
type: string
post:
operationId: submitScorecardScore
tags:
- Scorecards
summary: Submit a score for an entity
description: Submits or overrides a score for an entity on a Scorecard.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The recorded score.
'401':
$ref: '#/components/responses/Unauthorized'
/scorecards/{tag}/entity/{entityTag}/exemption:
parameters:
- $ref: '#/components/parameters/ScorecardTag'
- name: entityTag
in: path
required: true
schema:
type: string
post:
operationId: requestExemption
tags:
- Scorecards
summary: Request a scorecard exemption
description: Requests a time-boxed exemption from a Scorecard rule for an entity.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The requested exemption.
'401':
$ref: '#/components/responses/Unauthorized'
/custom-data:
get:
operationId: getCustomDataAdvanced
tags:
- Custom Data
summary: Retrieve custom data (advanced)
description: >-
Advanced retrieval of custom data across entities, supporting keys with
non-alphanumeric characters. Full path is /catalog/custom-data.
responses:
'200':
description: Custom data entries.
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: bulkUpsertCustomData
tags:
- Custom Data
summary: Bulk add custom data
description: >-
Bulk operation to add multiple key/value pairs across many entities. Full
path is /catalog/custom-data.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Bulk upsert result.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/custom-data:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: listEntityCustomData
tags:
- Custom Data
summary: List custom data for an entity
description: Lists custom key/value data attached to an entity, with pagination.
responses:
'200':
description: Custom data entries for the entity.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: addEntityCustomData
tags:
- Custom Data
summary: Add custom data to an entity
description: Adds or creates a custom key/value data entry on an entity.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomDataInput'
responses:
'200':
description: The created custom data entry.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteEntityCustomData
tags:
- Custom Data
summary: Delete custom data from an entity
description: Deletes a custom data entry from an entity by key query parameter.
parameters:
- name: key
in: query
schema:
type: string
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/custom-data/{key}:
parameters:
- $ref: '#/components/parameters/TagOrId'
- name: key
in: path
required: true
schema:
type: string
get:
operationId: getEntityCustomDataByKey
tags:
- Custom Data
summary: Retrieve custom data by key
description: Retrieves a specific custom data entry on an entity by key.
responses:
'200':
description: The custom data entry.
'401':
$ref: '#/components/responses/Unauthorized'
/initiatives:
get:
operationId: listInitiatives
tags:
- Initiatives
summary: List initiatives
description: Lists all Initiatives in the workspace.
responses:
'200':
description: A list of initiatives.
content:
application/json:
schema:
$ref: '#/components/schemas/InitiativeList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createInitiative
tags:
- Initiatives
summary: Create an initiative
description: Creates a new Initiative campaign.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiativeInput'
responses:
'200':
description: The created initiative.
'401':
$ref: '#/components/responses/Unauthorized'
/initiatives/{cid}:
parameters:
- name: cid
in: path
required: true
description: 18-character auto-generated identifier for the Initiative.
schema:
type: string
get:
operationId: getInitiative
tags:
- Initiatives
summary: Retrieve an initiative
description: Retrieves a single Initiative by its cid.
responses:
'200':
description: The requested initiative.
content:
application/json:
schema:
$ref: '#/components/schemas/Initiative'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateInitiative
tags:
- Initiatives
summary: Update an initiative
description: Updates an existing Initiative.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiativeInput'
responses:
'200':
description: The updated initiative.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteInitiative
tags:
- Initiatives
summary: Delete an initiative
description: Deletes an Initiative by cid.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/deploys:
parameters:
- $ref: '#/components/parameters/TagOrId'
get:
operationId: listEntityDeploys
tags:
- Deploys
summary: List deploys for an entity
description: Lists deployment events recorded for a catalog entity.
responses:
'200':
description: A list of deploy events.
content:
application/json:
schema:
$ref: '#/components/schemas/DeployList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: addEntityDeploy
tags:
- Deploys
summary: Add a deploy for an entity
description: Records a new deployment event for a catalog entity.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeployInput'
responses:
'200':
description: The recorded deploy event.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteEntityDeploys
tags:
- Deploys
summary: Delete deploys for an entity
description: Deletes deploy events for an entity, optionally filtered by environment, sha, or type.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/catalog/{tagOrId}/deploys/{uuid}:
parameters:
- $ref: '#/components/parameters/TagOrId'
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
put:
operationId: updateEntityDeploy
tags:
- Deploys
summary: Update a deploy
description: Updates a single deploy event for an entity.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeployInput'
responses:
'200':
description: The updated deploy event.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteEntityDeploy
tags:
- Deploys
summary: Delete a deploy
description: Deletes a single deploy event by uuid.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/deploys/environments:
get:
operationId: listDeployEnvironments
tags:
- Deploys
summary: List deploy environments
description: Lists the deploy environments known to Cortex.
responses:
'200':
description: A list of environments.
'401':
$ref: '#/components/responses/Unauthorized'
/deploys/search:
get:
operationId: searchDeploys
tags:
- Deploys
summary: Search deploys
description: Searches deploy events across the catalog.
responses:
'200':
description: Matching deploy events.
'401':
$ref: '#/components/responses/Unauthorized'
/github/configurations:
get:
operationId: listGithubConfigurations
tags:
- Integrations
summary: List GitHub configurations
description: >-
Lists the GitHub integration configurations. GitHub is shown as the
exemplar; roughly thirty integrations follow this same configuration
pattern under their own path prefix.
responses:
'200':
description: A list of GitHub configurations.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteGithubConfigurations
tags:
- Integrations
summary: Delete all GitHub configurations
description: Deletes all GitHub integration configurations.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
/github/default-configuration:
get:
operationId: getGithubDefaultConfiguration
tags:
- Integrations
summary: Retrieve the default GitHub configuration
description: Retrieves the default GitHub integration configuration.
responses:
'200':
description: The default configuration.
'401':
$ref: '#/components/responses/Unauthorized'
/github/configurations/validate:
post:
operationId: validateGithubConfiguration
tags:
- Integrations
summary: Validate a GitHub configuration
description: Validates a GitHub integration configuration without saving it.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Validation result.
'401':
$ref: '#/components/responses/Unauthorized'
/github/configurations/app:
post:
operationId: addGithubAppConfiguration
tags:
- Integrations
summary: Add a GitHub App configuration
description: Adds a GitHub App integration configuration.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The created configuration.
'401':
$ref: '#/components/responses/Unauthorized'
/github/configurations/app/{alias}:
parameters:
- name: alias
in: path
required: true
schema:
type: string
put:
operationId: updateGithubAppConfiguration
tags:
- Integrations
summary: Update a GitHub App configuration
description: Updates a GitHub App integration configuration by alias.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The updated configuration.
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteGithubAppConfiguration
tags:
- Integrations
summary: Delete a GitHub App configuration
description: Deletes a GitHub App integration configuration by alias.
responses:
'200':
description: Deletion confirmation.
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
API key created in the Settings page of your Cortex workspace, passed as
Authorization: Bearer <token>.
parameters:
TagOrId:
name: tagOrId
in: path
required: true
description: The entity's x-cortex-tag or id. Tags with forward slashes must be URL-encoded.
schema:
type: string
ScorecardTag:
name: tag
in: path
required: true
description: The Scorecard tag.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid Bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Entity:
type: object
description: A catalog entity. Modeled/simplified - verify fields against Cortex docs.
properties:
tag:
type: string
name:
type: string
type:
type: string
description: e.g. service, resource, domain, or a custom entity type.
description:
type: string
groups:
type: array
items:
type: string
ownership:
type: object
additionalProperties: true
metadata:
type: object
additionalProperties: true
EntityList:
type: object
properties:
entities:
type: array
items:
$ref: '#/components/schemas/Entity'
page:
type: integer
totalPages:
type: integer
EntityDescriptor:
type: object
description: >-
An entity descriptor (x-cortex-* YAML/JSON) submitted to create or update
an entity. Modeled - see Cortex descriptor reference for full schema.
additionalProperties: true
EntityScorecardScores:
type: object
properties:
scorecardScores:
type: array
items:
type: object
properties:
scorecardName:
type: string
score:
type: number
scorePercentage:
type: number
totalPossibleScore:
type: number
ladderLevels:
type: array
items:
type: object
additionalProperties: true
Scorecard:
type: object
description: A Scorecard definition. Modeled/simplified.
properties:
tag:
type: string
name:
type: string
description:
type: string
rules:
type: array
items:
type: object
additionalProperties: true
ScorecardList:
type: object
properties:
scorecards:
type: array
items:
$ref: '#/components/schemas/Scorecard'
CustomDataInput:
type: object
required:
- key
- value
properties:
key:
type: string
value:
description: Arbitrary JSON value.
description:
type: string
CustomDataList:
type: object
properties:
customData:
type: array
items:
type: object
properties:
key:
type: string
value: {}
description:
type: string
source:
type: string
dateUpdated:
type: string
format: date-time
Initiative:
type: object
description: An Initiative campaign. Modeled/simplified.
properties:
cid:
type: string
name:
type: string
description:
type: string
scorecardTag:
type: string
targetDate:
type: string
format: date
InitiativeList:
type: object
properties:
initiatives:
type: array
items:
$ref: '#/components/schemas/Initiative'
InitiativeInput:
type: object
required:
- name
properties:
name:
type: string
description:
type: string
scorecardTag:
type: string
targetDate:
type: string
format: date
Deploy:
type: object
description: A deployment event. Modeled/simplified.
properties:
uuid:
type: string
format: uuid
sha:
type: string
title:
type: string
type:
type: string
environment:
type: string
timestamp:
type: string
format: date-time
DeployList:
type: object
properties:
deploys:
type: array
items:
$ref: '#/components/schemas/Deploy'
DeployInput:
type: object
properties:
sha:
type: string
title:
type: string
type:
type: string
environment:
type: string
timestamp:
type: string
format: date-time
Error:
type: object
properties:
message:
type: string
requestId:
type: string