Cortex Eng Intel: 1-Registry 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 Eng Intel: 1-Registry API'
  version: v1
servers:
- url: https://api.getcortexapp.com
  description: Cortex Cloud API host
security:
- bearerAuth: []
tags:
- name: 'Eng Intel: 1-Registry'
paths:
  /api/v1/eng-intel/registry/metrics/definitions:
    get:
      description: Discover all available engineering metrics and their metadata. Use this before querying metrics to understand what data is available and how to query it effectively.
      operationId: listMetricDefinitions
      parameters:
      - in: query
        name: view
        required: false
        schema:
          type: string
          default: basic
      - in: query
        name: key
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricDefinitionsResponse'
          description: Successfully retrieved metric definitions
        '400':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BasicMetricDefinitionsResponse'
                - $ref: '#/components/schemas/FullMetricDefinitionsResponse'
          description: Invalid query parameters or filters
        '403':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BasicMetricDefinitionsResponse'
                - $ref: '#/components/schemas/FullMetricDefinitionsResponse'
          description: Forbidden
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List available engineering metric definitions
      tags:
      - 'Eng Intel: 1-Registry'
      x-cortex-mcp-description: 'List all available engineering metric definitions.


        USAGE - Call this endpoint BEFORE querying metrics (queryPointInTimeMetrics):

        1. Once at start: Call with view=''basic'' to discover all available metrics - cache this response

        2. Before querying: Call with view=''full'' and key=METRIC_KEY to get query metadata for only the metrics you need

        3. Use cached metadata to construct valid point-in-time queries


        IMPORTANT: Do NOT call view=''full'' without a key filter. The unfiltered full view is very large.


        Cache responses in your context. Only refresh if no longer in your context window or explicitly requested (ex to check if metric readiness has changed).


        Query parameters:

        - view: ''basic'' (default) returns minimal info, ''full'' includes sources and query metadata

        - key: Filter metrics by key (supports multiple values and comma-separated lists)


        Full view provides query construction metadata:

        - supportedAggregations: Valid aggregation methods for the metric

        - orderByAttribute: Attribute path for sorting by metric values

        - groupByOptions[].key: Valid groupBy keys (use exact values, do NOT guess)

        - filterOptions[].key: Valid filter keys (use exact values, do NOT guess)


        Valid orderBy attributes for metric queries:

        - orderByAttribute: The metric value itself (returned in full view)

        - Source attributes: Any attribute from the metric''s source (e.g., "source_name.attribute_name")

        - Dimension attributes: Any attribute from related dimensions (e.g., "source_name.dimension_name.attribute_name")


        Filter operators by type (for constructing queries):

        - STRING: EQUAL, NOT_EQUAL, IS_NULL, IS_NOT_NULL, LIKE, NOT_LIKE, IN, NOT_IN, ANY

        - INTEGER/DECIMAL/DOUBLE: EQUAL, NOT_EQUAL, IS_NULL, IS_NOT_NULL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, IN, NOT_IN, BETWEEN, ANY

        - DATETIME/DATE: EQUAL, NOT_EQUAL, IS_NULL, IS_NOT_NULL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, BETWEEN

        - BOOLEAN: EQUAL, NOT_EQUAL, IS_NULL, IS_NOT_NULL, IN, NOT_IN

        - ARRAY: EQUAL, CONTAINS, IN


        Error responses:

        - 400: Invalid view parameter (must be ''basic'' or ''full'')

        - 403: Restricted Feature (contact help@cortex.io)'
      x-cortex-mcp-enabled: 'true'
components:
  schemas:
    GroupByOption:
      required:
      - displayName
      - key
      type: object
      properties:
        canonicalName:
          type: string
          description: Canonical dimension name before source-specific overrides (e.g. 'User' instead of 'Author')
        dimensionRole:
          type: string
          description: Role of this dimension in the source context (e.g. 'Authors', 'Reviewers', 'Assignees')
        dimensionRoleGroup:
          type: string
          description: Optional grouping key for dimensions that share a canonical concept across roles (e.g. 'User' groups Author / Reviewer / Assignee)
        displayName:
          type: string
          description: Human-readable label for this grouping
        key:
          type: string
          description: Field key to use in GROUP BY clause
      description: Available grouping options for aggregating metrics
    NotReady:
      type: object
      allOf:
      - $ref: '#/components/schemas/Readiness'
      - type: object
        properties:
          docsUrl:
            type: string
          hint:
            type: string
          providerDocsUrls:
            type: array
            items:
              $ref: '#/components/schemas/ProviderDocLink'
    Source:
      required:
      - attributes
      - category
      - description
      - dimensions
      - filterOptions
      - groupByOptions
      - name
      type: object
      properties:
        attributes:
          type: array
          description: Queryable fields available directly on this source
          items:
            $ref: '#/components/schemas/Attribute'
        category:
          type: string
          description: Category this source belongs to (e.g. 'Version Control', 'CI-CD') -- the axis the product groups metrics by in its selector
        description:
          type: string
          description: Human-readable description of what data this source provides
        dimensions:
          type: array
          description: Related entities that can be joined for additional context
          items:
            $ref: '#/components/schemas/Dimension'
        filterOptions:
          type: array
          description: Available filtering options for querying metrics
          items:
            $ref: '#/components/schemas/FilterOption'
        groupByOptions:
          type: array
          description: Available grouping options for aggregating metrics
          items:
            $ref: '#/components/schemas/GroupByOption'
        name:
          type: string
          description: Unique identifier for the source
      description: Map of source names to source metadata for query construction
    Attribute:
      required:
      - name
      - type
      type: object
      properties:
        description:
          type: string
          description: Human-readable description of what this field contains
        name:
          type: string
          description: Field name for use in queries
        type:
          type: string
          description: Data type - determines which filter operators are supported (see endpoint description)
          enum:
          - STRING
          - BOOLEAN
          - INTEGER
          - DECIMAL
          - DOUBLE
          - DATE
          - TREE
          - DATETIME
          - JSON
          - ARRAY
          - ENUM
          - UNSUPPORTED
      description: Queryable fields available on this dimension
    BasicMetricDefinition:
      required:
      - displayName
      - key
      - readiness
      type: object
      properties:
        description:
          type: string
          description: Description of what this metric measures
        displayName:
          type: string
          description: Human-readable name
        key:
          type: string
          description: Unique identifier for the metric (used in queries)
        readiness:
          oneOf:
          - $ref: '#/components/schemas/NotReady'
          - $ref: '#/components/schemas/Ready'
      description: List of available metric definitions with basic metadata
    FilterOption:
      required:
      - displayName
      - filter
      - key
      type: object
      properties:
        canonicalName:
          type: string
          description: Canonical dimension name before source-specific overrides (e.g. 'User' instead of 'Author')
        dimensionRole:
          type: string
          description: Role of this dimension in the source context (e.g. 'Authors', 'Reviewers', 'Assignees')
        dimensionRoleGroup:
          type: string
          description: Optional grouping key for dimensions that share a canonical concept across roles (e.g. 'User' groups Author / Reviewer / Assignee)
        displayName:
          type: string
          description: Human-readable label for this filter
        filter:
          type: string
          description: Specific attribute to filter on
        key:
          type: string
          description: Field key to reference in queries
      description: Available filtering options for querying metrics
    FullMetricDefinitionsResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/MetricDefinitionsResponse'
      - required:
        - metrics
        - sources
        type: object
        properties:
          metrics:
            type: array
            description: List of available metric definitions with full metadata
            items:
              $ref: '#/components/schemas/FullMetricDefinition'
          sources:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/Source'
            description: Map of source names to source metadata for query construction
      - $ref: '#/components/schemas/MetricDefinitionsResponseObject'
    FullMetricDefinition:
      required:
      - displayName
      - key
      - readiness
      type: object
      properties:
        description:
          type: string
          description: Description of what this metric measures
        displayName:
          type: string
          description: Human-readable name
        key:
          type: string
          description: Unique identifier for the metric (used in queries)
        orderByAttribute:
          type: string
          description: The attribute used for ordering/sorting metric results
        readiness:
          oneOf:
          - $ref: '#/components/schemas/NotReady'
          - $ref: '#/components/schemas/Ready'
        sourceRef:
          type: string
          description: Reference to the data source in the sources map - indicates which integration provides this metric
        supportedAggregations:
          type: array
          description: Available aggregation functions for this metric (e.g., SUM, AVG, COUNT)
          items:
            type: string
            description: Available aggregation functions for this metric (e.g., SUM, AVG, COUNT)
            enum:
            - SUM
            - AVG
            - COUNT
            - RATIO
            - MIN
            - MAX
            - P50
            - P95
            - RANKING
            - COLLECT
            - COLLECT_UNIQUE
            - COUNT_UNIQUE
            - LATEST
        timeAttribute:
          $ref: '#/components/schemas/Attribute'
        type:
          type: string
          description: 'Type of metric: COUNT (discrete values), DURATION (time-based), RATIO/RATE (percentages), VALUE (continuous)'
          enum:
          - DURATION
          - COUNT
          - VALUE
          - RATE
        units:
          type: string
          description: Units of measurement (e.g., 'seconds', 'count', 'percentage')
        valence:
          type: string
          description: Whether higher values are better (POSITIVE) or worse (NEGATIVE) for this metric
          enum:
          - POSITIVE
          - NEGATIVE
          - NEUTRAL
      description: List of available metric definitions with full metadata
    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
    BasicMetricDefinitionsResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/MetricDefinitionsResponse'
      - required:
        - metrics
        type: object
        properties:
          metrics:
            type: array
            description: List of available metric definitions with basic metadata
            items:
              $ref: '#/components/schemas/BasicMetricDefinition'
      - $ref: '#/components/schemas/MetricDefinitionsResponseObject'
    MetricDefinitionsResponseObject:
      required:
      - metrics
      - view
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
        view:
          type: string
      discriminator:
        propertyName: view
    MetricDefinition:
      required:
      - displayName
      - key
      - readiness
      type: object
      properties:
        description:
          type: string
        displayName:
          type: string
        key:
          type: string
        readiness:
          oneOf:
          - $ref: '#/components/schemas/NotReady'
          - $ref: '#/components/schemas/Ready'
    Ready:
      type: object
      allOf:
      - $ref: '#/components/schemas/Readiness'
    Readiness:
      required:
      - type
      type: object
      properties:
        type:
          type: string
      description: Whether this metric is ready to use - includes hints if configuration is needed
      discriminator:
        propertyName: type
    MetricDefinitionsResponse:
      required:
      - metrics
      - view
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricDefinition'
        view:
          type: string
      discriminator:
        propertyName: view
    Dimension:
      required:
      - attributes
      - description
      - dimensionKey
      - displayName
      - name
      type: object
      properties:
        attributes:
          type: array
          description: Queryable fields available on this dimension
          items:
            $ref: '#/components/schemas/Attribute'
        description:
          type: string
          description: Description of the relationship this dimension represents
        dimensionKey:
          type: string
          description: Unprefixed base name identifying the dimension type across sources
        displayName:
          type: string
          description: Human-readable role of this dimension in the source context (e.g., Author, Reviewer)
        name:
          type: string
          description: Dimension identifier for use in queries
      description: Related entities that can be joined for additional context
    ProviderDocLink:
      required:
      - provider
      - url
      type: object
      properties:
        provider:
          type: string
        url:
          type: string
  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)