Cortex Entity Relationship Types API

openapi: 3.2.0
info:
  description: The Cortex REST API provides programmatic access to the data in the catalog, Scorecards, and more.
  title: Cortex Entity Relationship Types API
  version: v1
servers:
- url: https://api.getcortexapp.com
  description: Cortex Cloud API host
security:
- bearerAuth: []
tags:
- name: Entity Relationship Types
paths:
  /api/v1/relationship-types:
    get:
      description: List paginated relationship types
      operationId: listRelationshipTypes
      parameters:
      - description: Number of results to return per page, between 1 and 1000. Default 250.
        in: query
        name: pageSize
        required: true
        schema:
          type: integer
          format: int32
          default: 250
      - description: Page number to return, 0-indexed. Default 0.
        in: query
        name: page
        required: true
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEntityRelationshipTypeResponse'
          description: Successfully found entity relationship types
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List relationship types
      tags:
      - Entity Relationship Types
      x-cortex-mcp-description: List all available relationship types with pagination. View relationship type configurations to understand what kinds of relationships can be created between entities like services, resources, domains, and teams.
      x-cortex-mcp-enabled: 'true'
    post:
      description: Create a relationship type
      operationId: createRelationshipType
      requestBody:
        content:
          application/json:
            examples:
              Entity Relationship Type Example:
                description: Entity Relationship Type Example
                summary: Creates a relationship type that groups services into components
                value: "{\n                        \"name\": \"Component Hierarchy\",\n                        \"tag\": \"component-hierarchy\",\n                        \"description\": \"Defines the component hierarchy.\",\n                        \"definitionLocation\": \"BOTH\",\n                        \"isSingleSource\": true,\n                        \"sourcesFilter\": {\n                            \"include\": true,\n                            \"types\": [\"component\"]\n                        },\n                        \"isSingleDestination\": false,\n                        \"destinationsFilter\": {\n                            \"include\": true,\n                            \"types\": [\"service\", \"component]\n                        },\n                        \"inheritances\": [\n                            {\n                                \"parameterTag\": \"x-cortex-owners\",\n                                \"inheritanceType\": \"FALLBACK\"\n                            }\n                        ],\n                        \"allowCycles\": false,\n                        \"sourceLabelSingular\": \"Component\",\n                        \"sourceLabelPlural\": \"Components\",\n                        \"destinationLabelSingular\": \"Part\",\n                        \"destinationLabelPlural\": \"Parts\",\n                        \"createCatalog\": false\n                    }"
            schema:
              $ref: '#/components/schemas/EntityRelationshipTypeRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityRelationshipTypeResponse'
          description: Successfully created relationship type
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error creating relationship type
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create relationship type
      tags:
      - Entity Relationship Types
      x-cortex-mcp-description: Create a relationship type. Set its tag and name, the entity types allowed as sources and as destinations, single-source and single-destination limits, whether cycles are allowed, where relationships can be defined (definitionLocation), and the parameters entities inherit through it. Pass createCatalog=true to also create a catalog page for it. To change an existing type, use updateRelationshipType.
      x-cortex-mcp-enabled: 'true'
  /api/v1/relationship-types/{relationshipTypeTag}:
    delete:
      operationId: deleteRelationshipType
      parameters:
      - in: path
        name: relationshipTypeTag
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted relationship type
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error deleting relationship type
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Delete a relationship type
      tags:
      - Entity Relationship Types
      x-cortex-mcp-enabled: 'false'
    get:
      description: List details for a relationship type
      operationId: getRelationshipTypeDetails
      parameters:
      - in: path
        name: relationshipTypeTag
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityRelationshipTypeResponse'
          description: Successfully found relationship type
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Relationship type not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get a relationship type
      tags:
      - Entity Relationship Types
      x-cortex-mcp-description: Get complete details of a specific relationship type including its configuration, rules, source/destination filters, and inheritance settings. Essential for understanding how entities can be connected and what validation rules apply.
      x-cortex-mcp-enabled: 'true'
    put:
      operationId: updateRelationshipType
      parameters:
      - in: path
        name: relationshipTypeTag
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityRelationshipTypeRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityRelationshipTypeResponse'
          description: Successfully updated relationship type
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error updating relationship type
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Update relationship type
      tags:
      - Entity Relationship Types
      x-cortex-mcp-description: Replace the configuration of an existing relationship type, found by its tag. The request body is the full definition, and fields you leave out are not kept. Relationship types managed by Cortex cannot be changed. Read the current configuration with getRelationshipTypeDetails first.
      x-cortex-mcp-enabled: 'true'
components:
  schemas:
    EntityRelationshipTypeInheritanceView:
      required:
      - inheritanceType
      - parameterTag
      type: object
      properties:
        inheritanceType:
          type: string
          description: How relationship inheritance should be handled for this parameter
          enum:
          - NONE
          - FALLBACK
          - APPEND
          - CONFIGURE_AT_SOURCE
        parameterTag:
          type: string
      description: Inheritance configuration for Cortex parameters. Currently supports ownership inheritance via x-cortex-owners.
    PaginatedEntityRelationshipTypeResponse:
      required:
      - page
      - relationshipTypes
      - total
      - totalPages
      type: object
      properties:
        page:
          type: integer
          description: Current page number, 0-indexed
          format: int32
        relationshipTypes:
          type: array
          items:
            $ref: '#/components/schemas/EntityRelationshipTypeResponse'
        total:
          type: integer
          description: Total number of results
          format: int32
        totalPages:
          type: integer
          description: Total number of pages
          format: int32
    TooManyRequestsProblemDetail:
      required:
      - type
      - title
      - status
      type: object
      properties:
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        retryAfter:
          minimum: 0
          type: integer
          description: The number of seconds until the rate limiting resets.
          format: int32
        status:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          enum:
          - 429
        title:
          type: string
        type:
          type: string
          format: uri-reference
    ErrorResponse:
      required:
      - message
      - type
      type: object
      properties:
        details:
          type: string
        errorCode:
          type: string
        gatewayHttpStatus:
          type: integer
          format: int32
        httpStatus:
          type: integer
          format: int32
        message:
          type: string
        requestId:
          type: string
        type:
          type: string
          enum:
          - INTEGRATION_MISSING
          - INTEGRATION_UNREGISTERED
          - INTEGRATION_UNSUPPORTED
          - INTEGRATION_GRAPHQL_ERROR
          - INTEGRATION_BAD_REQUEST
          - INTEGRATION_UNAUTHORIZED
          - INTEGRATION_FORBIDDEN
          - INTEGRATION_NOT_FOUND
          - INTEGRATION_UNPROCESSABLE_CONTENT
          - INTEGRATION_RATE_LIMITED
          - INTEGRATION_INTERNAL_ERROR
          - INTEGRATION_NOT_IMPLEMENTED
          - INTEGRATION_BAD_GATEWAY
          - INTEGRATION_UNAVAILABLE
          - INTEGRATION_GATEWAY_TIMEOUT
          - INTEGRATION_TIMED_OUT
          - INTEGRATION_CACHE_ERROR
          - INTEGRATION_UNHANDLED_HTTP_ERROR
          - INTEGRATION_UNHANDLED_EXCEPTION
          - INTEGRATION_UNEXPECTED_ERROR
          - ILLEGAL_ARGUMENT_ERROR
          - BAD_REQUEST
          - FORBIDDEN
          - NOT_FOUND
          - REQUEST_TIMEOUT
          - CONFLICT
          - UNHANDLED_EXCEPTION
          - UNCATEGORIZED
          - SERVICE_CREATOR
          - UNKNOWN_HOST
          - TOO_MANY_REQUESTS
    EntityRelationshipTypeRequest:
      required:
      - allowCycles
      - createCatalog
      - definitionLocation
      - destinationsFilter
      - inheritances
      - isSingleDestination
      - isSingleSource
      - name
      - sourcesFilter
      - tag
      type: object
      properties:
        allowCycles:
          type: boolean
          description: Whether cyclical relationships are allowed
          example: false
        createCatalog:
          type: boolean
          description: Whether to create a catalog page for this relationship type
          example: false
        definitionLocation:
          type: string
          description: Defines where a relationship can be configured in entity descriptors
          example: BOTH
          enum:
          - SOURCE
          - DESTINATION
          - BOTH
        description:
          type: string
          description: Optional description explaining the relationship type
          example: Defines the component hierarchy
        destinationLabelPlural:
          type: string
          description: Plural label for destinations in the relationship
          example: Parts
        destinationLabelSingular:
          type: string
          description: Singular label for destinations in the relationship
          example: Part
        destinationsFilter:
          $ref: '#/components/schemas/EntityTypeFilter'
        inheritances:
          type: array
          description: Inheritance configuration for Cortex parameters. Currently supports ownership inheritance via x-cortex-owners.
          items:
            $ref: '#/components/schemas/EntityRelationshipTypeInheritanceView'
        isSingleDestination:
          type: boolean
          description: Whether an entity can have only one destination for this relationship type
          example: false
        isSingleSource:
          type: boolean
          description: Whether an entity can have only one source for this relationship type
          example: false
        name:
          type: string
          description: Human-readable name for the relationship type
          example: Component Hierarchy
        sourceLabelPlural:
          type: string
          description: Plural label for sources in the relationship
          example: Components
        sourceLabelSingular:
          type: string
          description: Singular label for sources in the relationship
          example: Component
        sourcesFilter:
          $ref: '#/components/schemas/EntityTypeFilter'
        tag:
          type: string
          description: Unique identifier tag for the relationship type
          example: component-hierarchy
      description: Request to create or update a relationship type
    EntityTypeFilter:
      required:
      - include
      - providers
      - types
      type: object
      properties:
        include:
          type: boolean
        providers:
          uniqueItems: true
          type: array
          items:
            type: string
            enum:
            - AWS
            - GCP
            - AZURE
        types:
          uniqueItems: true
          type: array
          items:
            type: string
    EntityRelationshipTypeResponse:
      required:
      - allowCycles
      - definitionLocation
      - destinationsFilter
      - inheritances
      - isCortexManaged
      - isSingleDestination
      - isSingleSource
      - name
      - sourcesFilter
      - tag
      type: object
      properties:
        allowCycles:
          type: boolean
          description: Whether cyclical relationships are allowed
          example: false
        definitionLocation:
          type: string
          description: Defines where a relationship can be configured in entity descriptors
          example: BOTH
          enum:
          - SOURCE
          - DESTINATION
          - BOTH
        description:
          type: string
          description: Optional description explaining the relationship type
          example: Defines the component hierarchy
        destinationLabelPlural:
          type: string
          description: Plural label for destinations in the relationship
          example: Parts
        destinationLabelSingular:
          type: string
          description: Singular label for destinations in the relationship
          example: Part
        destinationNamePlural:
          type: string
        destinationNameSingular:
          type: string
        destinationsFilter:
          $ref: '#/components/schemas/EntityTypeFilter'
        inheritances:
          type: array
          description: Inheritance configuration for Cortex parameters. Currently supports ownership inheritance via x-cortex-owners.
          items:
            $ref: '#/components/schemas/EntityRelationshipTypeInheritanceView'
        isCortexManaged:
          type: boolean
          description: Whether this relationship type is managed by Cortex
          example: false
        isSingleDestination:
          type: boolean
          description: Whether an entity can have only one destination for this relationship type
          example: false
        isSingleSource:
          type: boolean
          description: Whether an entity can have only one source for this relationship type
          example: false
        name:
          type: string
          description: Human-readable name for the relationship type
          example: Component Hierarchy
        sourceLabelPlural:
          type: string
          description: Plural label for sources in the relationship
          example: Components
        sourceLabelSingular:
          type: string
          description: Singular label for sources in the relationship
          example: Component
        sourceNamePlural:
          type: string
        sourceNameSingular:
          type: string
        sourcesFilter:
          $ref: '#/components/schemas/EntityTypeFilter'
        tag:
          type: string
          description: Unique identifier tag for the relationship type
          example: component-hierarchy
      description: Response containing relationship type details
  responses:
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsProblemDetail'
      description: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
      headers:
        Retry-After:
          description: The number of seconds until the rate limiting resets.
          schema:
            minimum: 0
            type: integer
            format: int32
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: '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.'
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Cortex
  source: https://docs.cortex.io/openapi/cortex_swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)