REST API Locators
In the scope of the TeamCity REST API, a locator is a string within a URL that allows filtering objects affected by a request.
In a REST API URL:
the <restApiPath> part can be:
.../app/rest/<items>— returns a list of objects (for example,.../app/rest/builds)..../app/rest/<items>/<item_locator>— includes a locator that filters the<items>list and returns only an object that matches the specified criteria (for example,.../app/rest/builds/id:15).
The Autogenerated REST API Reference | Locators section of this documentation contains locators for filtering TeamCity objects. Data schemas of these objects (object fields and their data types) are described in the Autogenerated REST API Reference | Models section.
For example, you can use ProjectLocator to filter TeamCity projects and use the Project data schema for reference.
See the Common Use Cases section for examples on how to use locators for the most popular scenarios. For example, you can learn how to get project details and explore other common use cases related to projects.
Locator Dimensions
A locator can include one or multiple dimensions that set filtering criteria for the requested entities:
One dimension:
.../app/rest/<items>/<dmnsn>:<value>For example,
.../projects/name:MyProject— finds a project by its name.Multiple dimensions:
.../app/rest/<items>/<dmnsn1>:<value1>,<dmnsn2>:<value2>For example,
.../builds/buildType:MyBuildConfigID,branch:MyBranch— finds a build of theMyBuildConfigIDbuild configuration run on theMyBranchbranch.
A locator's dimension value can be specified as another locator (nested locator) that includes its own dimension(s). Nested locators should be enclosed in parentheses: <dmnsn1>:<value1>,<dmnsn2>:(<dmnsn2.1>:<value2.1>,<dmnsn2.2>:<value2.2>).
For example, .../builds/buildType:(name:MyBuildConfigName) — finds the latest build of the build configuration with the MyBuildConfigName name.
To learn what dimensions are supported by a given locator, you can:
Refer to the locator description in the Autogenerated REST API Reference | Locators section. For example, the BuildLocator article lists dimensions available for the locator that filters builds.
Send a request with
$helpas the locator value. For example,.../app/rest/builds/$help.
If you send a request with an invalid locator, you will get an error message and a list of dimensions supported by the locator.
To shorten a URL path, you can omit a locator's <dmnsn>: part and pass a single value in some requests. Usually, it is an object ID, but some objects can also be found by their internal IDs or names. For example, you can find a build with the 105 ID as follows: http://<teamcityserver>:<port>/app/rest/builds/105.
A single value should be alphanumeric text without symbols like ,, :, -, (, ). If this value contains the , character, enclose it in parentheses: (<value>).
While a shorter URL form works great for quick requests, using the full form offers better readability and maintainability. We encourage you to explicitly specify locators' dimensions whenever possible.
List of Objects in Response
A URL like .../app/rest/<items>/<item_locator> returns a single item. If a locator matches several items, the first one is returned. The sorting order of objects depends on their type. For example, builds and changes are sorted by date in descending order (a locator finds the latest build/change); build configurations and projects are sorted by their IDs in alphabetical order.
To get a list of objects matching the locator, use the locator parameter in a URL.
Examples:
.../builds/buildType:MyBuildConfig— returns the first build of theMyBuildConfigbuild configuration (a Build object that includes all fields of a build)..../builds/?locator=buildType:MyBuildConfig— returns all builds of theMyBuildConfigbuild configuration (a Builds object that includes only basic fields for each build).
Note that both these request types (those that return a single item and a list of items) support the fields request parameter that you can use to change a set of fields returned in a response.