openapi: 3.0.3
info:
  title: TeamCity REST API
  description: >-
    The TeamCity REST API provides programmatic access to JetBrains TeamCity
    continuous integration and deployment server. It allows you to manage
    projects, build configurations, builds, agents, users, VCS roots, changes,
    tests, and other TeamCity resources.
  version: 2024.12.1
  contact:
    name: JetBrains
    url: https://www.jetbrains.com/support/teamcity/
    email: teamcity-support@jetbrains.com
  license:
    name: Proprietary
    url: https://www.jetbrains.com/teamcity/buy/
  x-logo:
    url: https://www.jetbrains.com/teamcity/img/teamcity-logo.svg

externalDocs:
  description: TeamCity REST API Documentation
  url: https://www.jetbrains.com/help/teamcity/rest-api.html

servers:
  - url: https://{server}/app/rest
    description: TeamCity Server
    variables:
      server:
        default: teamcity.example.com
        description: Your TeamCity server hostname

security:
  - bearerAuth: []
  - basicAuth: []

tags:
  - name: Projects
    description: Manage TeamCity projects
  - name: Build Configurations
    description: Manage build configurations (build types)
  - name: Builds
    description: Trigger, query, and manage builds
  - name: Build Queue
    description: Manage the build queue
  - name: Agents
    description: Manage build agents
  - name: Agent Pools
    description: Manage agent pools
  - name: VCS Roots
    description: Manage version control system roots
  - name: Changes
    description: Query VCS changes
  - name: Tests
    description: Query test results
  - name: Users
    description: Manage users and user groups
  - name: User Groups
    description: Manage user groups
  - name: Investigations
    description: Manage build and test investigations
  - name: Mutes
    description: Manage test mutes
  - name: Problems
    description: Query build problems
  - name: Server
    description: Server information and configuration
  - name: Cloud
    description: Manage cloud profiles and instances
  - name: Audit
    description: Query audit log entries

paths:
  /projects:
    get:
      operationId: getAllProjects
      summary: Get All Projects
      description: Returns a list of all projects on the TeamCity server.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects'
            application/xml:
              schema:
                $ref: '#/components/schemas/Projects'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      summary: Create Project
      description: Creates a new project on the TeamCity server.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewProjectDescription'
          application/xml:
            schema:
              $ref: '#/components/schemas/NewProjectDescription'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /projects/{projectLocator}:
    get:
      operationId: getProject
      summary: Get Project
      description: Returns details of a specific project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectLocator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProject
      summary: Delete Project
      description: Deletes a specific project from the TeamCity server.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectLocator'
      responses:
        '204':
          description: Project deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{projectLocator}/parameters:
    get:
      operationId: getProjectParameters
      summary: Get Project Parameters
      description: Returns all parameters defined for a project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectLocator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Properties'

  /projects/{projectLocator}/buildTypes:
    get:
      operationId: getProjectBuildTypes
      summary: Get Project Build Configurations
      description: Returns all build configurations for a project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectLocator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTypes'

  /buildTypes:
    get:
      operationId: getAllBuildTypes
      summary: Get All Build Configurations
      description: Returns a list of all build configurations.
      tags:
        - Build Configurations
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTypes'

  /buildTypes/{btLocator}:
    get:
      operationId: getBuildType
      summary: Get Build Configuration
      description: Returns details of a specific build configuration.
      tags:
        - Build Configurations
      parameters:
        - name: btLocator
          in: path
          required: true
          description: Build type locator string
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildType'
        '404':
          $ref: '#/components/responses/NotFound'

  /buildTypes/{btLocator}/builds:
    get:
      operationId: getBuildTypeBuilds
      summary: Get Build Configuration Builds
      description: Returns builds for a specific build configuration.
      tags:
        - Build Configurations
      parameters:
        - name: btLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Builds'

  /buildTypes/{btLocator}/parameters:
    get:
      operationId: getBuildTypeParameters
      summary: Get Build Configuration Parameters
      description: Returns all parameters defined for a build configuration.
      tags:
        - Build Configurations
      parameters:
        - name: btLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Properties'

  /builds:
    get:
      operationId: getAllBuilds
      summary: Get All Builds
      description: Returns a list of builds matching the specified criteria.
      tags:
        - Builds
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Builds'

  /builds/{buildLocator}:
    get:
      operationId: getBuild
      summary: Get Build
      description: Returns details of a specific build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          description: Build locator string
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '404':
          $ref: '#/components/responses/NotFound'

  /builds/{buildLocator}/tags:
    get:
      operationId: getBuildTags
      summary: Get Build Tags
      description: Returns tags associated with a build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'
    put:
      operationId: setBuildTags
      summary: Set Build Tags
      description: Sets tags for a build, replacing existing tags.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tags'
      responses:
        '200':
          description: Tags updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'

  /builds/{buildLocator}/artifacts:
    get:
      operationId: getBuildArtifacts
      summary: Get Build Artifacts
      description: Returns the artifacts of a specific build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'

  /builds/{buildLocator}/statistics:
    get:
      operationId: getBuildStatistics
      summary: Get Build Statistics
      description: Returns statistical values for a specific build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Properties'

  /builds/{buildLocator}/problemOccurrences:
    get:
      operationId: getBuildProblems
      summary: Get Build Problem Occurrences
      description: Returns problem occurrences for a specific build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemOccurrences'

  /builds/{buildLocator}/testOccurrences:
    get:
      operationId: getBuildTests
      summary: Get Build Test Occurrences
      description: Returns test occurrences for a specific build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestOccurrences'

  /builds/{buildLocator}/cancel:
    post:
      operationId: cancelBuild
      summary: Cancel Build
      description: Cancels a queued or running build.
      tags:
        - Builds
      parameters:
        - name: buildLocator
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildCancelRequest'
      responses:
        '200':
          description: Build cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'

  /buildQueue:
    get:
      operationId: getBuildQueue
      summary: Get Build Queue
      description: Returns the current build queue.
      tags:
        - Build Queue
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Builds'
    post:
      operationId: triggerBuild
      summary: Trigger Build
      description: Adds a build to the build queue (triggers a build).
      tags:
        - Build Queue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Build'
          application/xml:
            schema:
              $ref: '#/components/schemas/Build'
      responses:
        '200':
          description: Build triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '400':
          $ref: '#/components/responses/BadRequest'

  /agents:
    get:
      operationId: getAllAgents
      summary: Get All Agents
      description: Returns a list of all build agents.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agents'

  /agents/{agentLocator}:
    get:
      operationId: getAgent
      summary: Get Agent
      description: Returns details of a specific build agent.
      tags:
        - Agents
      parameters:
        - name: agentLocator
          in: path
          required: true
          description: Agent locator string
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          $ref: '#/components/responses/NotFound'

  /agents/{agentLocator}/enabled:
    get:
      operationId: getAgentEnabledStatus
      summary: Get Agent Enabled Status
      description: Returns whether an agent is enabled.
      tags:
        - Agents
      parameters:
        - name: agentLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: boolean
    put:
      operationId: setAgentEnabledStatus
      summary: Set Agent Enabled Status
      description: Enables or disables a build agent.
      tags:
        - Agents
      parameters:
        - name: agentLocator
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: boolean
      responses:
        '200':
          description: Status updated successfully

  /agents/{agentLocator}/authorized:
    get:
      operationId: getAgentAuthorizedStatus
      summary: Get Agent Authorized Status
      description: Returns whether an agent is authorized.
      tags:
        - Agents
      parameters:
        - name: agentLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: boolean
    put:
      operationId: setAgentAuthorizedStatus
      summary: Set Agent Authorized Status
      description: Authorizes or unauthorizes a build agent.
      tags:
        - Agents
      parameters:
        - name: agentLocator
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: boolean
      responses:
        '200':
          description: Status updated successfully

  /agentPools:
    get:
      operationId: getAllAgentPools
      summary: Get All Agent Pools
      description: Returns a list of all agent pools.
      tags:
        - Agent Pools
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPools'
    post:
      operationId: createAgentPool
      summary: Create Agent Pool
      description: Creates a new agent pool.
      tags:
        - Agent Pools
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentPool'
      responses:
        '200':
          description: Agent pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'

  /agentPools/{agentPoolLocator}:
    get:
      operationId: getAgentPool
      summary: Get Agent Pool
      description: Returns details of a specific agent pool.
      tags:
        - Agent Pools
      parameters:
        - name: agentPoolLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'
    delete:
      operationId: deleteAgentPool
      summary: Delete Agent Pool
      description: Deletes a specific agent pool.
      tags:
        - Agent Pools
      parameters:
        - name: agentPoolLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Agent pool deleted successfully

  /vcs-roots:
    get:
      operationId: getAllVcsRoots
      summary: Get All VCS Roots
      description: Returns a list of all VCS roots.
      tags:
        - VCS Roots
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VcsRoots'
    post:
      operationId: createVcsRoot
      summary: Create VCS Root
      description: Creates a new VCS root.
      tags:
        - VCS Roots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VcsRoot'
      responses:
        '200':
          description: VCS root created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VcsRoot'

  /vcs-roots/{vcsRootLocator}:
    get:
      operationId: getVcsRoot
      summary: Get VCS Root
      description: Returns details of a specific VCS root.
      tags:
        - VCS Roots
      parameters:
        - name: vcsRootLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VcsRoot'
    delete:
      operationId: deleteVcsRoot
      summary: Delete VCS Root
      description: Deletes a specific VCS root.
      tags:
        - VCS Roots
      parameters:
        - name: vcsRootLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: VCS root deleted successfully

  /changes:
    get:
      operationId: getAllChanges
      summary: Get All Changes
      description: Returns a list of VCS changes.
      tags:
        - Changes
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Changes'

  /changes/{changeLocator}:
    get:
      operationId: getChange
      summary: Get Change
      description: Returns details of a specific VCS change.
      tags:
        - Changes
      parameters:
        - name: changeLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'

  /testOccurrences:
    get:
      operationId: getAllTestOccurrences
      summary: Get All Test Occurrences
      description: Returns a list of test occurrences.
      tags:
        - Tests
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestOccurrences'

  /tests:
    get:
      operationId: getAllTests
      summary: Get All Tests
      description: Returns a list of tests.
      tags:
        - Tests
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tests'

  /users:
    get:
      operationId: getAllUsers
      summary: Get All Users
      description: Returns a list of all users.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
    post:
      operationId: createUser
      summary: Create User
      description: Creates a new user.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /users/{userLocator}:
    get:
      operationId: getUser
      summary: Get User
      description: Returns details of a specific user.
      tags:
        - Users
      parameters:
        - name: userLocator
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      operationId: updateUser
      summary: Update User
      description: Updates an existing user.
      tags:
        - Users
      parameters:
        - name: userLocator
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      operationId: deleteUser
      summary: Delete User
      description: Deletes a specific user.
      tags:
        - Users
      parameters:
        - name: userLocator
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User deleted successfully

  /userGroups:
    get:
      operationId: getAllUserGroups
      summary: Get All User Groups
      description: Returns a list of all user groups.
      tags:
        - User Groups
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Groups'
    post:
      operationId: createUserGroup
      summary: Create User Group
      description: Creates a new user group.
      tags:
        - User Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '200':
          description: Group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'

  /investigations:
    get:
      operationId: getAllInvestigations
      summary: Get All Investigations
      description: Returns a list of all investigations.
      tags:
        - Investigations
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigations'

  /mutes:
    get:
      operationId: getAllMutes
      summary: Get All Mutes
      description: Returns a list of all muted tests and problems.
      tags:
        - Mutes
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mutes'
    post:
      operationId: createMute
      summary: Create Mute
      description: Mutes a test or build problem.
      tags:
        - Mutes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Mute'
      responses:
        '200':
          description: Mute created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mute'

  /problemOccurrences:
    get:
      operationId: getAllProblemOccurrences
      summary: Get All Problem Occurrences
      description: Returns a list of build problem occurrences.
      tags:
        - Problems
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemOccurrences'

  /server:
    get:
      operationId: getServerInfo
      summary: Get Server Info
      description: Returns TeamCity server information including version and build number.
      tags:
        - Server
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'

  /server/plugins:
    get:
      operationId: getServerPlugins
      summary: Get Server Plugins
      description: Returns a list of installed server plugins.
      tags:
        - Server
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugins'

  /cloud/profiles:
    get:
      operationId: getAllCloudProfiles
      summary: Get All Cloud Profiles
      description: Returns a list of all cloud profiles.
      tags:
        - Cloud
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudProfiles'

  /cloud/instances:
    get:
      operationId: getAllCloudInstances
      summary: Get All Cloud Instances
      description: Returns a list of all cloud instances.
      tags:
        - Cloud
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudInstances'

  /audit:
    get:
      operationId: getAuditEvents
      summary: Get Audit Events
      description: Returns audit log events.
      tags:
        - Audit
      parameters:
        - $ref: '#/components/parameters/locator'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/start'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEvents'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using access tokens
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with username and password

  parameters:
    locator:
      name: locator
      in: query
      description: TeamCity locator string to filter results
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: Fields to include in the response (for partial responses)
      schema:
        type: string
    count:
      name: count
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        default: 100
    start:
      name: start
      in: query
      description: Index of the first item to return (for pagination)
      schema:
        type: integer
        default: 0
    projectLocator:
      name: projectLocator
      in: path
      required: true
      description: Project locator string (e.g., id:MyProject)
      schema:
        type: string

  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        text/plain:
          schema:
            type: string
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        text/plain:
          schema:
            type: string
    NotFound:
      description: Resource not found
      content:
        text/plain:
          schema:
            type: string

  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
          description: Project unique identifier
        name:
          type: string
          description: Project display name
        description:
          type: string
          description: Project description
        href:
          type: string
          description: Relative URL to this project resource
        webUrl:
          type: string
          description: URL to the project in the TeamCity web UI
        parentProjectId:
          type: string
          description: Parent project identifier
        archived:
          type: boolean
          description: Whether the project is archived
        buildTypes:
          $ref: '#/components/schemas/BuildTypes'
        parameters:
          $ref: '#/components/schemas/Properties'
        projects:
          $ref: '#/components/schemas/Projects'

    Projects:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        project:
          type: array
          items:
            $ref: '#/components/schemas/Project'

    NewProjectDescription:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Project display name
        id:
          type: string
          description: Project unique identifier
        parentProject:
          type: object
          properties:
            locator:
              type: string
        copyAllAssociatedSettings:
          type: boolean

    BuildType:
      type: object
      properties:
        id:
          type: string
          description: Build configuration unique identifier
        name:
          type: string
          description: Build configuration display name
        description:
          type: string
          description: Build configuration description
        projectName:
          type: string
          description: Name of the parent project
        projectId:
          type: string
          description: ID of the parent project
        href:
          type: string
        webUrl:
          type: string
        paused:
          type: boolean
        parameters:
          $ref: '#/components/schemas/Properties'
        steps:
          $ref: '#/components/schemas/Steps'
        triggers:
          $ref: '#/components/schemas/Triggers'
        settings:
          $ref: '#/components/schemas/Properties'

    BuildTypes:
      type: object
      properties:
        count:
          type: integer
        buildType:
          type: array
          items:
            $ref: '#/components/schemas/BuildType'

    Build:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Build unique identifier
        buildTypeId:
          type: string
          description: Build configuration identifier
        number:
          type: string
          description: Build number
        status:
          type: string
          enum:
            - SUCCESS
            - FAILURE
            - UNKNOWN
          description: Build status
        state:
          type: string
          enum:
            - queued
            - running
            - finished
          description: Build state
        statusText:
          type: string
          description: Build status text
        href:
          type: string
        webUrl:
          type: string
        branchName:
          type: string
          description: Branch name for the build
        startDate:
          type: string
          description: Build start date
        finishDate:
          type: string
          description: Build finish date
        queuedDate:
          type: string
          description: Date the build was queued
        triggered:
          $ref: '#/components/schemas/TriggeredBy'
        lastChanges:
          $ref: '#/components/schemas/Changes'
        agent:
          $ref: '#/components/schemas/Agent'
        testOccurrences:
          $ref: '#/components/schemas/TestOccurrences'
        problemOccurrences:
          $ref: '#/components/schemas/ProblemOccurrences'
        artifacts:
          $ref: '#/components/schemas/Files'
        properties:
          $ref: '#/components/schemas/Properties'
        statistics:
          $ref: '#/components/schemas/Properties'
        buildType:
          $ref: '#/components/schemas/BuildType'

    Builds:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        nextHref:
          type: string
        build:
          type: array
          items:
            $ref: '#/components/schemas/Build'

    BuildCancelRequest:
      type: object
      properties:
        comment:
          type: string
          description: Comment for cancellation
        readdIntoQueue:
          type: boolean
          description: Whether to re-add the build to the queue

    Agent:
      type: object
      properties:
        id:
          type: integer
          description: Agent unique identifier
        name:
          type: string
          description: Agent display name
        typeId:
          type: integer
          description: Agent type identifier
        connected:
          type: boolean
          description: Whether the agent is connected
        enabled:
          type: boolean
          description: Whether the agent is enabled
        authorized:
          type: boolean
          description: Whether the agent is authorized
        ip:
          type: string
          description: Agent IP address
        href:
          type: string
        webUrl:
          type: string
        pool:
          $ref: '#/components/schemas/AgentPool'
        properties:
          $ref: '#/components/schemas/Properties'
        build:
          $ref: '#/components/schemas/Build'

    Agents:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        agent:
          type: array
          items:
            $ref: '#/components/schemas/Agent'

    AgentPool:
      type: object
      properties:
        id:
          type: integer
          description: Agent pool unique identifier
        name:
          type: string
          description: Agent pool display name
        href:
          type: string
        maxAgents:
          type: integer
          description: Maximum number of agents in the pool
        agents:
          $ref: '#/components/schemas/Agents'
        projects:
          $ref: '#/components/schemas/Projects'

    AgentPools:
      type: object
      properties:
        count:
          type: integer
        agentPool:
          type: array
          items:
            $ref: '#/components/schemas/AgentPool'

    VcsRoot:
      type: object
      properties:
        id:
          type: string
          description: VCS root unique identifier
        name:
          type: string
          description: VCS root display name
        vcsName:
          type: string
          description: VCS type (e.g., jetbrains.git)
        href:
          type: string
        status:
          type: string
        lastChecked:
          type: string
        project:
          $ref: '#/components/schemas/Project'
        properties:
          $ref: '#/components/schemas/Properties'

    VcsRoots:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        vcs-root:
          type: array
          items:
            $ref: '#/components/schemas/VcsRoot'

    Change:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Change unique identifier
        version:
          type: string
          description: VCS revision
        username:
          type: string
          description: VCS username
        date:
          type: string
          description: Change date
        href:
          type: string
        webUrl:
          type: string
        comment:
          type: string
          description: Commit message
        user:
          $ref: '#/components/schemas/User'
        files:
          $ref: '#/components/schemas/FileChanges'

    Changes:
      type: object
      properties:
        count:
          type: integer
        change:
          type: array
          items:
            $ref: '#/components/schemas/Change'

    TestOccurrence:
      type: object
      properties:
        id:
          type: string
          description: Test occurrence identifier
        name:
          type: string
          description: Test name
        status:
          type: string
          enum:
            - SUCCESS
            - FAILURE
            - UNKNOWN
          description: Test status
        duration:
          type: integer
          description: Test duration in milliseconds
        href:
          type: string
        muted:
          type: boolean
        currentlyMuted:
          type: boolean
        currentlyInvestigated:
          type: boolean
        details:
          type: string
        build:
          $ref: '#/components/schemas/Build'
        test:
          $ref: '#/components/schemas/Test'

    TestOccurrences:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        testOccurrence:
          type: array
          items:
            $ref: '#/components/schemas/TestOccurrence'

    Test:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        href:
          type: string

    Tests:
      type: object
      properties:
        count:
          type: integer
        test:
          type: array
          items:
            $ref: '#/components/schemas/Test'

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: User unique identifier
        username:
          type: string
          description: User login name
        name:
          type: string
          description: User display name
        email:
          type: string
          description: User email address
        href:
          type: string
        lastLogin:
          type: string
        roles:
          $ref: '#/components/schemas/Roles'
        groups:
          $ref: '#/components/schemas/Groups'

    Users:
      type: object
      properties:
        count:
          type: integer
        user:
          type: array
          items:
            $ref: '#/components/schemas/User'

    Group:
      type: object
      properties:
        key:
          type: string
          description: Group key
        name:
          type: string
          description: Group display name
        description:
          type: string
        href:
          type: string
        roles:
          $ref: '#/components/schemas/Roles'

    Groups:
      type: object
      properties:
        count:
          type: integer
        group:
          type: array
          items:
            $ref: '#/components/schemas/Group'

    Roles:
      type: object
      properties:
        role:
          type: array
          items:
            $ref: '#/components/schemas/Role'

    Role:
      type: object
      properties:
        roleId:
          type: string
        scope:
          type: string
        href:
          type: string

    Investigation:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - TAKEN
            - FIXED
            - GIVEN_UP
        assignee:
          $ref: '#/components/schemas/User'
        assignment:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
            timestamp:
              type: string
            text:
              type: string
        scope:
          type: object
        target:
          type: object
        resolution:
          type: object

    Investigations:
      type: object
      properties:
        count:
          type: integer
        investigation:
          type: array
          items:
            $ref: '#/components/schemas/Investigation'

    Mute:
      type: object
      properties:
        id:
          type: integer
        href:
          type: string
        assignment:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
            timestamp:
              type: string
            text:
              type: string
        scope:
          type: object
        target:
          type: object
        resolution:
          type: object

    Mutes:
      type: object
      properties:
        count:
          type: integer
        mute:
          type: array
          items:
            $ref: '#/components/schemas/Mute'

    ProblemOccurrence:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        identity:
          type: string
        href:
          type: string
        details:
          type: string
        additionalData:
          type: string
        build:
          $ref: '#/components/schemas/Build'
        problem:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            identity:
              type: string

    ProblemOccurrences:
      type: object
      properties:
        count:
          type: integer
        problemOccurrence:
          type: array
          items:
            $ref: '#/components/schemas/ProblemOccurrence'

    Properties:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        property:
          type: array
          items:
            $ref: '#/components/schemas/Property'

    Property:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        inherited:
          type: boolean
        type:
          type: object
          properties:
            rawValue:
              type: string

    Steps:
      type: object
      properties:
        count:
          type: integer
        step:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: string
              properties:
                $ref: '#/components/schemas/Properties'

    Triggers:
      type: object
      properties:
        count:
          type: integer
        trigger:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              properties:
                $ref: '#/components/schemas/Properties'

    TriggeredBy:
      type: object
      properties:
        type:
          type: string
          description: Trigger type (user, vcs, schedule, etc.)
        details:
          type: string
        date:
          type: string
        user:
          $ref: '#/components/schemas/User'

    Tags:
      type: object
      properties:
        count:
          type: integer
        tag:
          type: array
          items:
            type: object
            properties:
              name:
                type: string

    Files:
      type: object
      properties:
        count:
          type: integer
        href:
          type: string
        file:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              size:
                type: integer
                format: int64
              modificationTime:
                type: string
              href:
                type: string
              content:
                type: object
                properties:
                  href:
                    type: string

    FileChanges:
      type: object
      properties:
        count:
          type: integer
        file:
          type: array
          items:
            type: object
            properties:
              beforeRevision:
                type: string
              afterRevision:
                type: string
              changeType:
                type: string
              file:
                type: string
              relativeFile:
                type: string

    Server:
      type: object
      properties:
        version:
          type: string
          description: TeamCity server version
        versionMajor:
          type: integer
        versionMinor:
          type: integer
        buildNumber:
          type: string
        buildDate:
          type: string
        currentTime:
          type: string
        startTime:
          type: string
        webUrl:
          type: string

    Plugins:
      type: object
      properties:
        count:
          type: integer
        plugin:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              displayName:
                type: string
              version:
                type: string

    CloudProfiles:
      type: object
      properties:
        count:
          type: integer
        cloudProfile:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              cloudProviderId:
                type: string
              href:
                type: string
              project:
                $ref: '#/components/schemas/Project'

    CloudInstances:
      type: object
      properties:
        count:
          type: integer
        cloudInstance:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              state:
                type: string
              startDate:
                type: string
              agent:
                $ref: '#/components/schemas/Agent'
              image:
                type: object
              profile:
                type: object

    AuditEvent:
      type: object
      properties:
        id:
          type: string
        timestamp:
          type: string
        action:
          type: string
        comment:
          type: string
        user:
          $ref: '#/components/schemas/User'

    AuditEvents:
      type: object
      properties:
        count:
          type: integer
        auditEvent:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'