TeamCity REST API

https://www.jetbrains.com/help/teamcity/rest/
Admin
TeamCity REST API enables integration of external applications with TeamCity servers through HTTP...
Tokens:359,653
Snippets:2,784
Trust Score:10
Update:4 days ago
Show doc for...
Tokens:
Raw
### POST /app/rest/2FA/setup

Source: https://www.jetbrains.com/help/teamcity/rest/manage-2fa.html

Starts the 2FA setup process for the current user. Returns a secret key, a set of recovery keys, and a UUID for confirming the setup.

```APIDOC
## POST /app/rest/2FA/setup

### Description
Starts the 2FA setup process for the current user. Returns a secret key, a set of recovery keys, and a UUID for confirming the setup.

### Method
POST

### Endpoint
/app/rest/2FA/setup

### Response
#### Success Response (200)
- **secretKey** (string) - The secret key for TOTP generation.
- **recoveryKeys** (array of strings) - A set of recovery keys.
- **uuid** (string) - UUID for confirming the setup.

#### Response Example
{
  "secretKey": "string",
  "recoveryKeys": ["string"],
  "uuid": "string"
}
```

--------------------------------

### Request builds with start index

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Example request demonstrating the default lookup limit behavior when starting at index 4999.

```HTTP
GET
/app/rest/builds?locator=start:4999
```

--------------------------------

### Start Custom Build Payload

Source: https://www.jetbrains.com/help/teamcity/rest/start-and-cancel-builds.html

Payload examples for a POST request to start a custom build with specific settings like personal status, branch, agent, comment, and properties.

```XML
<build personal="true" branchName="myBranch">
    <buildType id="MyBuildConfigID"/>
    <comment>
        <text>Build for testing REST API</text>
    </comment>
    <agent id="286"/>
    <properties>
        <property name="system.existingParameter" value="myValue"/>
        <property name="env.newPasswordParameter" value="mySecret">
            <type rawValue="password"/>
        </property>
    </properties>
</build>
```

```JSON
{
  "branchName": "myBranch",
  "personal": true,
  "buildType": {
    "id": "MyBuildConfigID"
  },
  "comment": {
    "text": "Build for testing REST API"
  },
  "agent": {
    "id": 286
  },
  "properties": {
    "property": [{
      "name": "system.existingParameter",
      "value": "myValue"
    },
      {
        "name": "env.password",
        "value": "mySecret",
        "type": {
          "rawValue": "password"
        }
      }
    ]
  }
}
```

--------------------------------

### Request builds with custom count and start

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Example request to retrieve 200 builds starting from the 50th record for the TC_Trunk project.

```HTTP
GET
/app/rest/builds?locator=project:TC_Trunk,count:200,start:50
```

--------------------------------

### Get project by ID

Source: https://www.jetbrains.com/help/teamcity/rest/get-project-details.html

Example of retrieving a project with the specific ID 'MyCustomProject'.

```HTTP
GET
/app/rest/projects/id:MyCustomProject
```

--------------------------------

### Start Cloud Instance

Source: https://www.jetbrains.com/help/teamcity/rest/manage-cloud-profiles.html

Initiate a request to start a new cloud instance.

```HTTP
POST
/app/rest/cloud/instances
```

--------------------------------

### Delete Project Example

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-projects.html

Example of deleting a project with the specific ID MyCustomProject.

```text
DELETE
/app/rest/projects/id:MyCustomProject
```

--------------------------------

### GET /app/rest/projects/{projectLocator}/settingsFile

Source: https://www.jetbrains.com/help/teamcity/rest/projectapi.html

Get the settings file of the matching build configuration.

```APIDOC
## GET /app/rest/projects/{projectLocator}/settingsFile

### Description
Get the settings file of the matching build configuration.

### Method
GET

### Endpoint
/app/rest/projects/{projectLocator}/settingsFile

### Parameters
#### Path Parameters
- **projectLocator** (string<ProjectLocator>) - Required - The project locator.

### Response
#### Success Response
- **Response** (string) - The settings file content.

### Produces
- text/plain
```

--------------------------------

### Browser-based Authentication Example

Source: https://www.jetbrains.com/help/teamcity/rest/teamcity-rest-api-documentation.html

Example of using browser-based authentication for GET requests when logged in to TeamCity.

```APIDOC
## GET /app/rest/builds

### Description
Access the REST API from within a browser when logged in to TeamCity.

### Authentication
- **Method**: Browser Session Authentication
- **URL**: /app/rest/builds

### Example
```
/app/rest/builds
```
```

--------------------------------

### Build Step Payload Example

Source: https://www.jetbrains.com/help/teamcity/rest/manage-build-configuration-details.html

Example payload for a command line step that prints 'Hello World!', provided in XML and JSON formats.

```xml
<steps>
  <step name="myCommandLineStep" type="simpleRunner">
    <properties count="4">
	  <property name="script.content" value="echo 'Hello World!'"/>
    </properties>
  </step>
</steps>
```

```json
{
	"name": "myCommandLineStep",
	"type": "simpleRunner",
	"properties": {
		"property": [
			{
				"name": "script.content",
				"value": "echo 'Hello World!'"
			}
		]
	}
}
```

--------------------------------

### Create Build Configuration Entity Examples

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-build-configurations.html

Example XML and JSON payloads for creating a build configuration.

```xml
<buildType description="string" id="string" name="string">
  <project id="MyProjectID"/>
  <templates>
	<buildType id="MyTemplateID"/>
  </templates>
  <parameters>
    <property name="myBuildParameter" value="myValue"/>
  </parameters>
  <steps>
    <step name="myCommandLineStep" type="simpleRunner">
      <properties count="4">
        <property name="script.content" value="echo 'Hello World!'"/>
      </properties>
    </step>
  </steps>
</buildType>
```

```json
{
    "id": "id",
    "name": "name",
    "project": {
        "id": "MyProjectID"
    },
    "templates": {
        "buildType": [
            {
                "id": "MyTemplateID"
            }
        ]
    },
    "parameters": {
        "property": [
            {
                "name": "myBuildParameter",
                "value": "myValue"
            }
        ]
    },
    "steps": {
        "step": [
            {
                "name": "myCommandLineStep",
                "type": "simpleRunner",
                "properties": {
                    "property": [
                        {
                            "name": "script.content",
                            "value": "echo 'Hello World!'"
                        }
                    ]
                }
            }
        ]
    }
}
```

--------------------------------

### Get builds with pagination

Source: https://www.jetbrains.com/help/teamcity/rest/get-build-details.html

Controls the number of returned builds and the starting position using the count and start dimensions.

```HTTP
GET
/app/rest/builds?locator=count:10,start:15
```

--------------------------------

### GET /app/rest/server/plugins

Source: https://www.jetbrains.com/help/teamcity/rest/serverapi.html

Retrieves all plugins installed on the server.

```APIDOC
## GET /app/rest/server/plugins

### Description
Get all plugins.

### Method
GET

### Endpoint
/app/rest/server/plugins

### Parameters
#### Query Parameters
- **fields** (string) - Optional - A set of fields to include in the response.
- **locator** (string) - Optional - A locator to filter plugins.

### Response
#### Success Response
- **Plugins** - The list of plugins.

### Produces
- application/xml
- application/json
```

--------------------------------

### Copy Build Configuration Entity Examples

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-build-configurations.html

Example XML and JSON payloads for copying a build configuration.

```xml
<newBuildTypeDescription copyAllAssociatedSettings="true" id="Source_Config_ID_Copy1" name="Source_Config_Name_Copy1" sourceBuildTypeLocator="id:Source_Config_ID" />
```

```json
{
    "sourceBuildTypeLocator": "id:Source_Config_ID",
    "name": "Source_Config_Name_Copy1",
    "id": "Source_Config_ID_Copy1",
    "copyAllAssociatedSettings": true
}
```

--------------------------------

### Set up version control settings

Source: https://www.jetbrains.com/help/teamcity/rest/manage-vcs-settings.html

Configures version control settings for the new project. Set importDecision to 'importFromVCS' to resolve conflicts during initial setup.

```http
PUT
/app/rest/projects/<PROJECT_ID>/versionedSettings/config
```

```xml
<versionedSettingsConfig
    allowUIEditing="true"
    buildSettingsMode="alwaysUseCurrent"
    format="kotlin"
    showSettingsChanges="false"
    storeSecureValuesOutsideVcs="true"
    synchronizationMode="enabled"
    vcsRootId="NewProjID_NewRootID"
    importDecision="importFromVCS"/>
```

```json
{
  "format": "kotlin",
  "synchronizationMode": "enabled",
  "allowUIEditing": true,
  "storeSecureValuesOutsideVcs": true,
  "portableDsl": true,
  "showSettingsChanges": true,
  "vcsRootId": "NewProjID_NewRootID",
  "buildSettingsMode": "alwaysUseCurrent",
  "importDecision": "importFromVCS"
}
```

--------------------------------

### Move Build Configuration Request Example

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-build-configurations.html

An example request to move a build configuration to a target project.

```text
POST
http://localhost:8111/app/rest/buildTypes/id:SourceProject_MyBuildConfig/move?targetProjectId=MyProject2
```

--------------------------------

### POST /app/rest/cloud/instances

Source: https://www.jetbrains.com/help/teamcity/rest/cloudinstanceapi.html

Start a new cloud instance. Accepts a CloudInstance body.

```APIDOC
## POST /app/rest/cloud/instances

### Description
Start a new cloud instance.

### Method
POST

### Endpoint
/app/rest/cloud/instances

### Parameters
#### Request Body
- **body** (CloudInstance) - Required - The cloud instance to start.

#### Query Parameters
- **fields** (string) - Optional - Fields to include in the response.

### Response
#### Success Response (200)
(No response body specified in source)
```

--------------------------------

### Create Project Payload Examples

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-projects.html

Example XML and JSON payloads for creating a new project, specifying the parent project, name, ID, and settings copy preference.

```xml
<newProjectDescription copyAllAssociatedSettings="true" id="string" name="string">
  <parentProject locator="string" />
</newProjectDescription>
```

```json
{
    "parentProject": {
        "locator": "locator"
    },
    "name": "name",
    "id": "id",
    "copyAllAssociatedSettings": true
}
```

--------------------------------

### List test history

Source: https://www.jetbrains.com/help/teamcity/rest/manage-tests-and-build-problems.html

Example request to get the test history for a test named MyTest.

```HTTP
GET
/app/rest/testOccurrences?locator=test:(name:MyTest)
```

--------------------------------

### Get Agent Name by ID

Source: https://www.jetbrains.com/help/teamcity/rest/manage-agents.html

Example request to retrieve the name of an agent with ID 1.

```HTTP
GET
/app/rest/agents/id:1/name
```

--------------------------------

### POST /app/rest/buildQueue (Rebuild All Dependencies)

Source: https://www.jetbrains.com/help/teamcity/rest/start-and-cancel-builds.html

Starts a build with triggering options to clean sources, rebuild all dependencies, and queue at top.

```APIDOC
## POST /app/rest/buildQueue

### Description
Starts a build with triggering options that control clean checkout, dependency rebuild, and queue priority.

### Method
POST

### Endpoint
/app/rest/buildQueue

### Parameters
#### Request Body
- **buildType** (object) - Required - Contains the build configuration ID.
  - **id** (string) - Required - The build configuration ID.
- **triggeringOptions** (object) - Required - Specifies build triggering options.
  - **cleanSources** (boolean) - Required - If true, performs a clean checkout.
  - **rebuildAllDependencies** (boolean) - Required - If true, rebuilds all dependencies.
  - **queueAtTop** (boolean) - Required - If true, places the build at the top of the queue.

### Request Example
{
  "buildType": {
    "id": "buildConfID"
  },
  "triggeringOptions": {
    "cleanSources": true,
    "rebuildAllDependencies": true,
    "queueAtTop": true
  }
}

### Response
#### Success Response (200)
Returns the created Build entity with the specified triggering options.

#### Response Example
{
  "id": 12345,
  "buildType": {
    "id": "buildConfID"
  },
  "triggeringOptions": {
    "cleanSources": true,
    "rebuildAllDependencies": true,
    "queueAtTop": true
  }
}
```

--------------------------------

### GET /app/rest/builds?locator=project:TC_Trunk,count:200,start:50

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Finds all builds of the 'TC_Trunk' project and returns a list of 200 builds starting with the 50th record. This demonstrates custom count and start values for pagination.

```APIDOC
## GET /app/rest/builds?locator=project:TC_Trunk,count:200,start:50

### Description
Finds all builds of the 'TC_Trunk' project and returns a list of 200 builds starting with the 50th record.

### Method
GET

### Endpoint
/app/rest/builds?locator=project:TC_Trunk,count:200,start:50

### Parameters
#### Query Parameters
- **locator** (string) - Required - The locator specifying the project and pagination parameters. In this example, project:TC_Trunk, count:200, start:50.

### Response
#### Success Response (200)
- **count** (integer) - The number of entities in this batch.
- **start** (integer) - The zero-based index of this batch's first record.
- **nextHref** (string) - The locator that allows you to view the next page.
- **prevHref** (string) - The locator that allows you to view the previous page.
```

--------------------------------

### List build problems for a specific build

Source: https://www.jetbrains.com/help/teamcity/rest/manage-tests-and-build-problems.html

Example request to get build problems for a build with ID 999.

```HTTP
GET
/app/rest/problemOccurrences?locator=build:(id:999)
```

--------------------------------

### List all build configurations

Source: https://www.jetbrains.com/help/teamcity/rest/manage-build-configuration-details.html

Retrieve all build configurations available on the server.

```HTTP
GET
/app/rest/buildTypes
```

--------------------------------

### VCS root payload examples

Source: https://www.jetbrains.com/help/teamcity/rest/manage-vcs-roots.html

Example XML and JSON payloads for creating a VCS root.

```XML
<vcs-root id="MyCustomRoot" name="MyCustomRoot" vcsName="jetbrains.git">
    <project id="MyCustomProject"/>
    <properties count="3">
        <property name="authMethod" value="ANONYMOUS"/>
        <property name="branch" value="refs/heads/master"/>
        <property name="url" value="https://mygitserver.com/myrepo"/>
    </properties>
</vcs-root>
```

```JSON
{
    "id": "MyCustomRoot",
    "name": "MyCustomRoot",
    "vcsName": "jetbrains.git",
    "project": {
        "id": "MyCustomProject"
    },
    "properties": {
        "property": [
            {
                "name": "authMethod",
                "value": "ANONYMOUS"
            },
            {
                "name": "branch",
                "value": "refs/heads/master"
            },
            {
                "name": "url",
                "value": "https://mygitserver.com/myrepo"
            }
        ]
    }
}
```

--------------------------------

### GET /app/rest/builds

Source: https://www.jetbrains.com/help/teamcity/rest/target%3D%22_blank%22

Example of using the fields parameter to request specific fields for builds. The response format is determined by the Accept header.

```APIDOC
## GET /app/rest/builds

### Description
Retrieves builds with a locator and specifies the fields to include in the response.

### Method
GET

### Endpoint
/app/rest/builds

### Parameters
#### Query Parameters
- **locator** (string) - Required - Locator to filter builds, e.g., buildType:(id:bt345),count:10
- **fields** (string) - Optional - Comma-separated list of fields to include, e.g., count,build(number,status,statusText,agent,lastChange,tags,pinned)

### Request Example
http://teamcity.jetbrains.com/app/rest/builds?locator=buildType:(id:bt345),count:10&fields=count,build(number,status,statusText,agent,lastChange,tags,pinned)

### Response
#### Success Response (200)
- **count** (integer) - Number of builds returned
- **build** (object) - Contains the requested fields: number, status, statusText, agent, lastChange, tags, pinned

#### Response Example
{
  "count": 10,
  "build": {
    "number": "...",
    "status": "...",
    "statusText": "...",
    "agent": "...",
    "lastChange": "...",
    "tags": "...",
    "pinned": "..."
  }
}
```

--------------------------------

### Start Backup POST Request

Source: https://www.jetbrains.com/help/teamcity/rest/manage-data-backup.html

Initiates a server backup using the specified filename and inclusion scopes. The backup is saved to the default backup directory.

```HTTP
POST
/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName=MyCustomBackup.zip
```

--------------------------------

### GET /app/rest/buildTypes

Source: https://www.jetbrains.com/help/teamcity/rest/target%3D%22_blank%22

Example of using the fields parameter to request specific fields for build types. The response format is determined by the Accept header.

```APIDOC
## GET /app/rest/buildTypes

### Description
Retrieves build types with a locator and specifies the fields to include in the response.

### Method
GET

### Endpoint
/app/rest/buildTypes

### Parameters
#### Query Parameters
- **locator** (string) - Required - Locator to filter build types, e.g., affectedProject:(id:TeamCityPluginsByJetBrains)
- **fields** (string) - Optional - Comma-separated list of fields to include, e.g., buildType(id,name,project)

### Request Example
http://teamcity.jetbrains.com/app/rest/buildTypes?locator=affectedProject:(id:TeamCityPluginsByJetBrains)&fields=buildType(id,name,project)

### Response
#### Success Response (200)
- **buildType** (object) - Contains the requested fields: id, name, project

#### Response Example
{
  "buildType": {
    "id": "...",
    "name": "...",
    "project": "..."
  }
}
```

--------------------------------

### GET /app/rest/users/<userLocator>

Source: https://www.jetbrains.com/help/teamcity/rest/manage-users.html

Retrieves details of a specific user identified by a user locator. The userLocator is typed as UserLocator, for example username:MyUsername.

```APIDOC
## GET /app/rest/users/<userLocator>

### Description
Retrieves details of a specific user identified by a user locator.

### Method
GET

### Endpoint
/app/rest/users/<userLocator>

### Parameters
#### Path Parameters
- **userLocator** (UserLocator) - Required - Locator of the user, e.g., username:MyUsername.

### Response
#### Success Response (200)
- **User entity** - Details of the requested user.

#### Response Example
{
  "username": "string",
  "name": "string",
  "email": "string"
}
```

--------------------------------

### GET /app/rest/builds?locator=start:4999

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Requests builds starting at index 4999. Due to the default lookup limit of 5000 entities, the response contains only one build.

```APIDOC
## GET /app/rest/builds?locator=start:4999

### Description
Requests builds starting at index 4999. Due to the default lookup limit of 5000 entities, the response contains only one build.

### Method
GET

### Endpoint
/app/rest/builds?locator=start:4999

### Parameters
#### Query Parameters
- **locator** (string) - Required - The locator specifying the start index. In this example, start:4999.

### Response
#### Success Response (200)
- **count** (integer) - The number of entities in this batch.
- **start** (integer) - The zero-based index of this batch's first record.
- **nextHref** (string) - The locator that allows you to view the next page.
- **prevHref** (string) - The locator that allows you to view the previous page.
```

--------------------------------

### Setup 2FA for current user

Source: https://www.jetbrains.com/help/teamcity/rest/manage-2fa.html

Initiates the 2FA setup process for the current user. Returns a secret key, recovery keys, and a UUID for confirmation.

```http
POST
/app/rest/2FA/setup
```

--------------------------------

### GET /app/rest/projects

Source: https://www.jetbrains.com/help/teamcity/rest/get-project-details.html

Retrieves a list of all projects on the server. The response is paginated and contains up to 100 recent projects. Use the count and start locator dimensions to control pagination.

```APIDOC
## GET /app/rest/projects

### Description
Retrieves a list of all projects on the server. The response is paginated and contains up to 100 recent projects. Use the count and start locator dimensions to control pagination.

### Method
GET

### Endpoint
/app/rest/projects

### Parameters
#### Query Parameters
- **locator** (string) - Optional - A locator string that can include count and start dimensions to control pagination. Example: count:10,start:15

### Response
#### Success Response (200)
- **Projects** (entity) - Contains up to 100 recent Project entities. Includes nextHref and prevHref properties for pagination.

#### Response Example
{
  "project": [
    {
      "id": "MyCustomProject",
      "name": "My Custom Project"
    }
  ],
  "count": 1,
  "href": "/app/rest/projects"
}
```

--------------------------------

### Get Build Steps Endpoint

Source: https://www.jetbrains.com/help/teamcity/rest/manage-build-configuration-details.html

Use this GET request to retrieve all build steps for a specific build configuration.

```text
GET
/app/rest/buildTypes/<buildTypeLocator>/steps
```

--------------------------------

### TestRunMetadata JSON schema example

Source: https://www.jetbrains.com/help/teamcity/rest/testrunmetadata.html

JSON representation of the TestRunMetadata object with typedValues array and count field. Use as a base for POST requests after fetching via GET.

```json
{
  "typedValues" : [ "typedValue..." ],
  "count" : 6
}
```

--------------------------------

### Copy Project Payload Examples

Source: https://www.jetbrains.com/help/teamcity/rest/create-and-delete-projects.html

Example XML and JSON payloads for copying an existing project, requiring a sourceProject locator.

```xml
<newProjectDescription copyAllAssociatedSettings="true" id="string" name="string">
  <sourceProject locator="string" />
  <parentProject locator="string" />
</newProjectDescription>
```

```json
{
    "parentProject": {
        "locator": "locator"
    },
    "name": "name",
    "id": "id",
    "copyAllAssociatedSettings": true,
    "sourceProject": {
        "locator": "locator"
    }
}
```

--------------------------------

### TestRunMetadata XML schema example

Source: https://www.jetbrains.com/help/teamcity/rest/testrunmetadata.html

XML representation of the TestRunMetadata object with a count attribute and a typedValues element. Use as a base for POST requests after fetching via GET.

```xml
<testRunMetadata count="123">
  <typedValues>typedValue...</typedValues>
</testRunMetadata>
```

--------------------------------

### AuditEvent JSON schema example

Source: https://www.jetbrains.com/help/teamcity/rest/auditevent.html

Full JSON representation of an AuditEvent object. Shows the structure with action, relatedEntities, and user objects. Use as a base for POST requests after retrieving via GET.

```json
{
  "action" : {
    "name" : "build_type_edit_settings",
    "pattern" : "#{0} build configuration settings were edited (#{1}).",
    "id" : "54"
  },
  "comment" : "runners of 'Retrieve Issues' build configuration were updated",
  "id" : "94",
  "relatedEntities" : {
    "count" : 3,
    "entity" : [ {
      "agent" : "agent...",
      "vcsRoot" : "vcs-root...",
      "test" : "test...",
      "change" : "change...",
      "project" : "project...",
      "type" : "type",
      "unknown" : true,
      "internalId" : "internalId",
      "problem" : "problem...",
      "build" : "build...",
      "buildType" : "buildType...",
      "text" : "text",
      "agentPool" : "agentPool...",
      "user" : "user...",
      "group" : "group..."
    } ]
  },
  "user" : {
    "lastLogin" : "20241001T155514+0200",
    "roles" : {
      "role" : [ "roleAssignment..." ]
    },
    "groups" : {
      "count" : 2,
      "group" : [ "group..." ]
    },
    "hasPassword" : true,
    "password" : "foobar",
    "enabled2FA" : false,
    "name" : "John Doe",
    "realm" : "realm",
    "id" : 1,
    "href" : "/app/rest/users/id:11",
    "locator" : "null",
    "email" : "email",
    "properties" : {
      "count" : 1,
      "property" : [ {
        "inherited" : true,
        "name" : "name",
        "type" : "type...",
        "value" : "value"
      } ],
      "href" : "href"
    },
    "username" : "johndoe",
    "avatars" : {
      "urlToSize80" : "/app/rest/avatars/id:1/80/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize28" : "/app/rest/avatars/id:1/28/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize40" : "/app/rest/avatars/id:1/40/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize32" : "/app/rest/avatars/id:1/32/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize20" : "/app/rest/avatars/id:1/20/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize64" : "/app/rest/avatars/id:1/64/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png",
      "urlToSize56" : "/app/rest/avatars/id:1/56/avatar.a0b4af01-0211-4216-b2de-c295b282b4b5.png"
    }
  },
  "timestamp" : "20250326T163632+0100"
}
```

--------------------------------

### Build Authentication Example

Source: https://www.jetbrains.com/help/teamcity/rest/teamcity-rest-api-documentation.html

Example of using system properties as credentials within a TeamCity build for limited build-related operations.

```APIDOC
## GET /httpAuth/app/rest/builds/id:%teamcity.build.id%

### Description
Access current build details from within a TeamCity build using system properties as basic credentials.

### Authentication
- **Method**: Basic HTTP Authentication
- **Credentials**: teamcity.auth.userId and teamcity.auth.password system properties

### Example
```
curl -u "%system.teamcity.auth.userId%:%system.teamcity.auth.password%" "%teamcity.serverUrl%/httpAuth/app/rest/builds/id:%teamcity.build.id%"
```
```

--------------------------------

### AuditEvent XML schema example

Source: https://www.jetbrains.com/help/teamcity/rest/auditevent.html

Full XML representation of an AuditEvent object. Shows the structure with action, relatedEntities, and user elements. Use as a base for POST requests after retrieving via GET.

```xml
<auditEvent comment="runners of 'Retrieve Issues' build configuration were updated" id="94" timestamp="20250326T163632+0100">
  <action id="54" name="build_type_edit_settings" pattern="#{0} build configuration settings were edited (#{1})."/>
  <relatedEntities count="123">
    <entity>relatedEntity...</entity>
  </relatedEntities>
  <user email="string" enabled2FA="false" hasPassword="true" href="/app/rest/users/id:11" id="1" lastLogin="20241001T155514+0200" locator="null" name="John Doe" password="foobar" realm="string" username="johndoe">
    <properties>properties...</properties>
    <roles>roleAssignments...</roles>
    <groups>groups...</groups>
    <avatars>userAvatars...</avatars>
  </user>
</auditEvent>
```

--------------------------------

### Get all build parameters

Source: https://www.jetbrains.com/help/teamcity/rest/manage-build-configuration-details.html

Retrieve all parameters for a specific build configuration.

```HTTP
GET
/app/rest/buildTypes/<buildTypeLocator>/parameters
```

--------------------------------

### GET /app/rest/buildTypes/{btLocator}/settingsFile

Source: https://www.jetbrains.com/help/teamcity/rest/buildtypeapi.html

Retrieves the settings file of the specified build configuration. The response is returned as plain text.

```APIDOC
## GET /app/rest/buildTypes/{btLocator}/settingsFile

### Description
Get the settings file of the matching build configuration.

### Method
GET

### Endpoint
/app/rest/buildTypes/{btLocator}/settingsFile

### Parameters
#### Path Parameters
- **btLocator** (string<BuildTypeLocator>) - Required - The build type locator.

### Response
#### Success Response (200)
- **body** (string) - The settings file content.

#### Response Example
(plain text content)
```

--------------------------------

### GET /app/rest/builds

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Retrieves builds filtered by a locator that includes nested locators for build type and start date. The startDate dimension can accept a nested BuildLocator to filter builds relative to a specific build.

```APIDOC
## GET /app/rest/builds

### Description
Retrieves builds filtered by a locator that includes nested locators for build type and start date. The startDate dimension can accept a nested BuildLocator to filter builds relative to a specific build.

### Method
GET

### Endpoint
/app/rest/builds

### Parameters
#### Query Parameters
- **locator** (string) - Required - A locator string that can include nested locators. Examples: `buildType:TC_Trunk_Compile,startDate:(date:20200101T000000%2B0100,condition:after),status:failure` or `buildType:TC_Trunk_Compile,startDate:(build:281819048,condition:after),status:failure`.

### Request Example
GET /app/rest/builds?locator=buildType:TC_Trunk_Compile,startDate:(build:281819048,condition:after),status:failure

### Response
#### Success Response (200)
Returns a list of builds matching the locator.

#### Error Response (404)
Returns "404: Not Found" if the locator is invalid or cannot be resolved.
```

--------------------------------

### POST /app/rest/buildQueue

Source: https://www.jetbrains.com/help/teamcity/rest/start-and-cancel-builds.html

Starts a custom build with settings that differ from its build configuration, such as personal flag, branch, agent, comment, and custom properties.

```APIDOC
## POST /app/rest/buildQueue

### Description
Starts a new build with custom settings. The request body contains a Build entity with fields to override the build configuration defaults.

### Method
POST

### Endpoint
/app/rest/buildQueue

### Parameters
#### Request Body
- **personal** (boolean) - Optional - Marks the build as personal.
- **branchName** (string) - Optional - Specifies the branch to run the build in.
- **buildType** (object) - Required - Contains the build configuration ID.
  - **id** (string) - Required - The build configuration ID.
- **comment** (object) - Optional - Provides a description for the build.
  - **text** (string) - Required - The comment text.
- **agent** (object) - Optional - Selects a specific agent.
  - **id** (integer) - Required - The agent ID.
- **properties** (object) - Optional - Sets custom build parameters.
  - **property** (array) - Optional - List of property objects.
    - **name** (string) - Required - The property name.
    - **value** (string) - Required - The property value.
    - **type** (object) - Optional - The property type.
      - **rawValue** (string) - Required - The raw type value.

### Request Example
{
  "branchName": "myBranch",
  "personal": true,
  "buildType": {
    "id": "MyBuildConfigID"
  },
  "comment": {
    "text": "Build for testing REST API"
  },
  "agent": {
    "id": 286
  },
  "properties": {
    "property": [
      {
        "name": "system.existingParameter",
        "value": "myValue"
      },
      {
        "name": "env.password",
        "value": "mySecret",
        "type": {
          "rawValue": "password"
        }
      }
    ]
  }
}

### Response
#### Success Response (200)
Returns the created Build entity with the applied settings.

#### Response Example
{
  "id": 12345,
  "personal": true,
  "branchName": "myBranch",
  "buildType": {
    "id": "MyBuildConfigID"
  },
  "comment": {
    "text": "Build for testing REST API"
  },
  "agent": {
    "id": 286
  },
  "properties": {
    "property": [
      {
        "name": "system.existingParameter",
        "value": "myValue"
      },
      {
        "name": "env.password",
        "value": "mySecret",
        "type": {
          "rawValue": "password"
        }
      }
    ]
  }
}
```

--------------------------------

### Confirm 2FA setup

Source: https://www.jetbrains.com/help/teamcity/rest/manage-2fa.html

Confirms the 2FA setup using the UUID from the setup method and a 6-digit TOTP password.

```http
POST
/app/rest/2FA/confirm?uuid=<uuid>&password=<password>
```

--------------------------------

### Request builds with lookupLimit

Source: https://www.jetbrains.com/help/teamcity/rest/locators.html

Example request overriding the default 5000 entity limit to process 7000 builds and return a specific range.

```HTTP
GET
/app/rest/builds?locator=start:6000,lookupLimit:7000
```

--------------------------------

### GET /app/rest/investigations/{investigationLocator}

Source: https://www.jetbrains.com/help/teamcity/rest/investigationapi.html

Get investigation matching the locator.

```APIDOC
## GET /app/rest/investigations/{investigationLocator}

### Description
Get investigation matching the locator.

### Method
GET

### Endpoint
/app/rest/investigations/{investigationLocator}

### Parameters
#### Path Parameters
- **investigationLocator** (string<InvestigationLocator>) - Required - The locator of the investigation to retrieve.

#### Query Parameters
- **fields** (string) - Optional - Fields to include in the response.

### Response
#### Success Response (200)
- **Investigation** - The investigation matching the locator.

#### Response Example
```json
{
  "id": 1,
  "state": "NEW"
}
```
```

--------------------------------

### GET /app/rest/projects/{locator}/versionedSettings/tokens

Source: https://www.jetbrains.com/help/teamcity/rest/versionedsettingsapi.html

Get Versioned Settings Tokens.

```APIDOC
## GET /app/rest/projects/{locator}/versionedSettings/tokens

### Description
Get Versioned Settings Tokens.

### Method
GET

### Endpoint
/app/rest/projects/{locator}/versionedSettings/tokens

### Parameters
#### Path Parameters
- **locator** (string<ProjectLocator>) - Required - Project locator.

#### Query Parameters
- **status** (string) - Optional - Status filter.

### Response
#### Success Response (200)
- **VersionedSettingsTokens** - The tokens.
```

--------------------------------

### Start Regular Build Endpoint

Source: https://www.jetbrains.com/help/teamcity/rest/start-and-cancel-builds.html

The endpoint used to access the build queue for starting a new build.

```text
POST
/app/rest/buildQueue
```
Tokens:
Raw