Cortex My Workspace 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 My Workspace API
  version: v1
servers:
- url: https://api.getcortexapp.com
  description: Cortex Cloud API host
security:
- bearerAuth: []
tags:
- name: My Workspace
paths:
  /api/v1/mcp/my/workspace:
    post:
      description: Retrieve various types of resources owned by or assigned to the current user
      operationId: getMyWorkspace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MyWorkspaceRequestWrapper'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyWorkspaceResponse'
          description: Successfully retrieved resources
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyWorkspaceResponse'
          description: Invalid resource type or parameters
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyWorkspaceResponse'
          description: Authentication required
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get resources for the authenticated user
      tags:
      - My Workspace
      x-cortex-mcp-description: "TOOL for retrieving current user's owned resources and work items across the Cortex workspace.\n\n        FLEXIBLE REQUEST STRUCTURE:\n        The request accepts an object with optional fields for each resource type:\n        - myEntitiesRequest: Fetch entities (services, resources, domains) owned by the user\n        - myTeamsRequest: Fetch teams the user belongs to\n        - myScorecardsRequest: Fetch scorecards associated with user's entities\n        - myOpenPRsRequest: Fetch user's open pull requests across all Git repositories\n        - myRequestedReviewsRequest: Fetch PRs where user is requested as a reviewer\n        - myWorkItemsRequest: Fetch work items (Jira, Linear, Azure DevOps) assigned to the user\n\n        Set one or more fields to fetch multiple resource types in a single call.\n        All results are combined into a single response array with mixed item types.\n\n        RESPONSE STRUCTURE:\n        Returns a single array of items where each item has an 'itemType' field indicating its type:\n        - 'entity': Catalog entities (services, resources, domains)\n        - 'team': Teams the user belongs to\n        - 'scorecard': Scorecards for user's entities\n        - 'pull_request': Open pull requests authored by the user\n        - 'review_request': Pull requests where user is requested as reviewer\n        - 'work_item': Work items (issues/tickets) assigned to the user\n\n        EXAMPLES:\n        1. Fetch only services:\n           {\"myEntitiesRequest\": {\"entityTypes\": [\"service\"]}}\n\n        2. Fetch teams and their entities:\n           {\"myTeamsRequest\": {\"includeMembers\": true}, \"myEntitiesRequest\": {}}\n\n        3. Get all work (PRs, reviews, Jira tickets):\n           {\"myOpenPRsRequest\": {}, \"myRequestedReviewsRequest\": {}, \"myWorkItemsRequest\": {}}\n\n        4. Search entities with filters:\n           {\"myEntitiesRequest\": {\"query\": \"payment\", \"ownershipSource\": \"DIRECT\", \"entityTypes\": [\"service\", \"resource\"]}}\n        "
      x-cortex-mcp-enabled: 'true'
      x-internal: true
components:
  schemas:
    RepositoryInfo:
      required:
      - name
      - url
      type: object
      properties:
        name:
          type: string
          description: Repository name
        url:
          type: string
          description: Repository URL
      description: Repository details
    Role:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: Name of the role
          example: Team Leader
        source:
          type: string
          description: Source of the role if pulled in through integration. This will be blank if manually defined in Cortex.
          example: WORKDAY
    MyWorkspaceRequestWrapper:
      type: object
      properties:
        myEntitiesRequest:
          $ref: '#/components/schemas/Entities'
        myOpenPRsRequest:
          $ref: '#/components/schemas/OpenPRs'
        myRequestedReviewsRequest:
          $ref: '#/components/schemas/RequestedReviews'
        myScorecardsRequest:
          $ref: '#/components/schemas/Scorecards'
        myTeamsRequest:
          $ref: '#/components/schemas/Teams'
        myWorkItemsRequest:
          $ref: '#/components/schemas/WorkItems'
      description: "\n        Request wrapper for fetching user's workspace. Supports fetching multiple resource types in a single call.\n        Set one or more of the request fields to fetch the corresponding resources. Results will be combined into a single response.\n\n        Examples:\n        - Fetch entities only: {\"myEntitiesRequest\": {\"ownershipSource\": \"DIRECT\", \"entityTypes\": [\"service\"]}}\n        - Fetch teams only: {\"myTeamsRequest\": {\"includeMembers\": true}}\n        - Fetch both entities and teams: {\"myEntitiesRequest\": {...}, \"myTeamsRequest\": {...}}\n    "
    PullRequestInfo:
      required:
      - number
      - title
      - url
      type: object
      properties:
        number:
          type: integer
          description: PR number
          format: int64
        title:
          type: string
          description: PR title
        url:
          type: string
          description: PR URL
      description: Pull request details
    MyWorkspaceItem:
      required:
      - itemType
      type: object
      properties:
        itemType:
          type: string
      description: Item returned in My Workspace response - type varies by resourceType
      discriminator:
        mapping:
          entity: '#/components/schemas/Entity'
          pull_request: '#/components/schemas/PullRequest'
          review_request: '#/components/schemas/ReviewRequest'
          scorecard: '#/components/schemas/Scorecard'
          team: '#/components/schemas/Team'
          work_item: '#/components/schemas/WorkItem'
        propertyName: itemType
      oneOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/Team'
      - $ref: '#/components/schemas/Scorecard'
      - $ref: '#/components/schemas/PullRequest'
      - $ref: '#/components/schemas/ReviewRequest'
      - $ref: '#/components/schemas/WorkItem'
    WorkItemStatus:
      required:
      - statusBackgroundColor
      - statusIconColor
      - statusText
      - statusType
      type: object
      properties:
        statusBackgroundColor:
          type: string
          description: Status background color
        statusIconColor:
          type: string
          description: Status icon color
        statusText:
          type: string
          description: Status text
        statusType:
          type: string
          description: Status type
      description: Work item status information
    TeamMemberSource:
      required:
      - type
      type: object
      properties:
        externalGroupId:
          type: string
        externalId:
          type: string
        provider:
          type: string
          enum:
          - ACTIVE_DIRECTORY
          - BAMBOO_HR
          - GITHUB
          - GITLAB
          - GOOGLE
          - OKTA
          - OPSGENIE
          - WORKDAY
          - SERVICE_NOW
        type:
          type: string
          enum:
          - ENTITY_DEFINED
          - IDP_GROUP
    RequestedReviews:
      required:
      - placeholder
      type: object
      properties:
        placeholder:
          type: boolean
          description: No additional parameters required - returns all review requests for the user
      description: Request for pull requests where the user is requested as a reviewer
    WorkItem:
      type: object
      description: Work item (Jira, Linear, Azure DevOps issue) assigned to the user
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - id
        - source
        - status
        - title
        - url
        type: object
        properties:
          alias:
            type: string
            description: Work item alias/key
          dueDate:
            type: string
            description: Due date
            format: date-time
          id:
            type: string
            description: Work item ID
          project:
            $ref: '#/components/schemas/WorkItemProject'
          source:
            type: string
            description: Issue tracking system (Jira, Linear, Azure)
            enum:
            - AZURE_DEVOPS_WORK_ITEMS
            - CLICKUP
            - GITHUB
            - JIRA
          status:
            $ref: '#/components/schemas/WorkItemStatus'
          title:
            type: string
            description: Work item title
          url:
            type: string
            description: URL to the work item
    Teams:
      required:
      - includeMembers
      - page
      - pageSize
      type: object
      properties:
        includeMembers:
          type: boolean
          description: Include team member details (name, email, description)
        page:
          type: integer
          description: Page number to return, 0-indexed. Default 0.
          format: int32
          example: 0
        pageSize:
          type: integer
          description: Number of results to return per page, between 1 and 1000. Default 250.
          format: int32
          example: 250
      description: Request for teams the user belongs to
    Entity:
      type: object
      description: Catalog entity (service, resource, or domain) owned by the user
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - archived
        - cid
        - name
        - tag
        - type
        type: object
        properties:
          archived:
            type: boolean
            description: Whether the entity is archived
          cid:
            type: string
            description: Entity CID
          name:
            type: string
            description: Entity name
          tag:
            type: string
            description: Entity tag
          type:
            type: string
            description: Entity type (service, resource, domain)
    Scorecards:
      required:
      - ownershipSource
      type: object
      properties:
        ownershipSource:
          type: string
          description: Source of ownership (DIRECT, INHERITED, ALL)
          enum:
          - DIRECT
          - TEAM_HIERARCHY
      description: Request for scorecards associated with the user's entities
    OpenPRs:
      required:
      - placeholder
      type: object
      properties:
        placeholder:
          type: boolean
          description: No additional parameters required - returns all open PRs for the user
      description: Request for user's open pull requests across all Git repositories
    Entities:
      required:
      - includeArchived
      - ownershipSource
      - page
      - pageSize
      type: object
      properties:
        entityTypes:
          type: array
          description: Filter by entity types
          example:
          - service
          - resource
          - domain
          items:
            type: string
            description: Filter by entity types
            example: '["service","resource","domain"]'
        includeArchived:
          type: boolean
          description: Include archived entities
        ownershipSource:
          type: string
          description: Source of ownership (DIRECT, INHERITED, ALL)
          enum:
          - DIRECT
          - TEAM_HIERARCHY
        page:
          type: integer
          description: Page number to return, 0-indexed. Default 0.
          format: int32
          example: 0
        pageSize:
          type: integer
          description: Number of results to return per page, between 1 and 1000. Default 250.
          format: int32
          example: 250
        query:
          type: string
          description: Optional search query to filter entities by name or other properties
      description: Request for all entities (services, resources, domains) owned by the user
    MyWorkspaceResponse:
      required:
      - items
      type: object
      properties:
        items:
          type: array
          description: Mixed array of resources. Each item's type is indicated by its 'itemType' field.
          items:
            $ref: '#/components/schemas/MyWorkspaceItem'
      description: Unified response containing workspace resources of various types (entities, teams, scorecards, etc.)
    TeamMember:
      required:
      - roles
      - sources
      type: object
      properties:
        description:
          type: string
          description: Description of the team member
          example: Product manager
        email:
          type: string
          description: Email of the team member
          example: aditya.bansal@cortex.io
        name:
          type: string
          description: Name of the team member
          example: Aditya Bansal
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/TeamMemberSource'
      description: Team member information
    PullRequest:
      type: object
      description: Pull request authored by the user
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - dateOpened
        - entityCids
        - entityIds
        - isComplex
        - isDraft
        - isOld
        - isQuick
        - lastUpdated
        - numComments
        - numReviewers
        - pullRequest
        - repository
        - source
        - status
        type: object
        properties:
          dateOpened:
            type: string
            description: Date the PR was opened
          entityCids:
            type: array
            description: CIDs of entities associated with this PR
            items:
              type: string
              description: CIDs of entities associated with this PR
          entityIds:
            type: array
            description: IDs of entities associated with this PR
            items:
              type: integer
              description: IDs of entities associated with this PR
              format: int64
          isComplex:
            type: boolean
            description: Whether the PR is considered complex
          isDraft:
            type: boolean
            description: Whether the PR is a draft
          isOld:
            type: boolean
            description: Whether the PR is considered old
          isQuick:
            type: boolean
            description: Whether the PR is considered quick
          lastUpdated:
            type: string
            description: Last update timestamp
          numComments:
            type: integer
            description: Number of comments
            format: int32
          numFilesChanged:
            type: integer
            description: Number of files changed
            format: int32
          numLinesAdded:
            type: integer
            description: Number of lines added
            format: int32
          numLinesDeleted:
            type: integer
            description: Number of lines deleted
            format: int32
          numReviewers:
            type: integer
            description: Number of reviewers
            format: int32
          pullRequest:
            $ref: '#/components/schemas/PullRequestInfo'
          repository:
            $ref: '#/components/schemas/RepositoryInfo'
          source:
            type: string
            description: Git provider (GitHub, GitLab, etc.)
            enum:
            - AZURE_DEVOPS
            - BITBUCKET
            - GITHUB
            - GITLAB
          status:
            type: string
            description: Review status
            enum:
            - APPROVED
            - CHANGES_REQUESTED
            - REVIEW_REQUIRED
    WorkItems:
      required:
      - page
      - pageSize
      type: object
      properties:
        page:
          type: integer
          description: Page number for pagination (0-indexed)
          format: int32
          example: 0
        pageSize:
          type: integer
          description: Maximum number of work items to return
          format: int32
          example: 50
      description: Request for work items (Jira, Linear, Azure DevOps issues) assigned to the user
    ReviewRequest:
      type: object
      description: Pull request where the user is requested as a reviewer
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - dateOpened
        - entityCids
        - entityIds
        - isComplex
        - isDraft
        - isOld
        - isQuick
        - lastUpdated
        - numComments
        - numReviewers
        - pullRequest
        - repository
        - source
        - status
        type: object
        properties:
          dateOpened:
            type: string
            description: Date the PR was opened
          entityCids:
            type: array
            description: CIDs of entities associated with this PR
            items:
              type: string
              description: CIDs of entities associated with this PR
          entityIds:
            type: array
            description: IDs of entities associated with this PR
            items:
              type: integer
              description: IDs of entities associated with this PR
              format: int64
          isComplex:
            type: boolean
            description: Whether the PR is considered complex
          isDraft:
            type: boolean
            description: Whether the PR is a draft
          isOld:
            type: boolean
            description: Whether the PR is considered old
          isQuick:
            type: boolean
            description: Whether the PR is considered quick
          lastUpdated:
            type: string
            description: Last update timestamp
          numComments:
            type: integer
            description: Number of comments
            format: int32
          numFilesChanged:
            type: integer
            description: Number of files changed
            format: int32
          numLinesAdded:
            type: integer
            description: Number of lines added
            format: int32
          numLinesDeleted:
            type: integer
            description: Number of lines deleted
            format: int32
          numReviewers:
            type: integer
            description: Number of reviewers
            format: int32
          pullRequest:
            $ref: '#/components/schemas/PullRequestInfo'
          repository:
            $ref: '#/components/schemas/RepositoryInfo'
          source:
            type: string
            description: Git provider (GitHub, GitLab, etc.)
            enum:
            - AZURE_DEVOPS
            - BITBUCKET
            - GITHUB
            - GITLAB
          status:
            type: string
            description: Review status
            enum:
            - APPROVED
            - CHANGES_REQUESTED
            - REVIEW_REQUIRED
    WorkItemProject:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: Project name
        url:
          type: string
          description: Project URL
      description: Work item project details
    Scorecard:
      type: object
      description: Scorecard associated with user's entities
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - draft
        - name
        - tag
        type: object
        properties:
          description:
            type: string
            description: Scorecard description
          draft:
            type: boolean
            description: Whether the scorecard is a draft
          name:
            type: string
            description: Scorecard name
          tag:
            type: string
            description: Scorecard tag
    Team:
      type: object
      description: Team that the user belongs to
      allOf:
      - $ref: '#/components/schemas/MyWorkspaceItem'
      - required:
        - cid
        - name
        - tag
        type: object
        properties:
          cid:
            type: string
            description: Team CID
          description:
            type: string
            description: Team description
          members:
            type: array
            description: Team members (only populated if includeMembers is true)
            items:
              $ref: '#/components/schemas/TeamMember'
          name:
            type: string
            description: Team name
          tag:
            type: string
            description: Team tag
    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
  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)