The teamcity api command lets you make authenticated HTTP requests to the TeamCity REST API directly from the command line. This is useful for accessing API endpoints not yet covered by dedicated CLI commands, building custom scripts, and debugging.
Basic usage
The endpoint argument is the path portion of the URL, starting with /app/rest/:
teamcity api /app/rest/server
The CLI automatically adds the base URL and authentication headers based on your current authentication context.
HTTP methods
By default, requests use the GET method. Specify a different method with -X:
# GET (default)
teamcity api /app/rest/projects
# POST
teamcity api /app/rest/buildQueue -X POST -f 'buildType=id:MyBuild'
# PUT
teamcity api /app/rest/builds/12345/comment -X PUT --input comment.txt
# DELETE
teamcity api /app/rest/builds/12345/tags/obsolete -X DELETE
Sending data
JSON fields
Use -f to build a JSON request body from key-value pairs:
teamcity api /app/rest/buildQueue -X POST -f 'buildType=id:MyBuild'
teamcity api /app/rest/buildQueue -X POST -f 'buildType=id:MyBuild' -f 'branchName=main'
Request body from a file
Use --input to read the request body from a file:
teamcity api /app/rest/projects -X POST --input project.json
Read from stdin with --input -:
echo '{"name": "New Project"}' | teamcity api /app/rest/projects -X POST --input -
Custom headers
Add custom headers with -H:
teamcity api /app/rest/builds -H "Accept: application/xml"
Response handling
Include response headers
teamcity api /app/rest/server -i
Raw output
Output the response without formatting:
teamcity api /app/rest/server --raw
Silent mode
Suppress output on success (useful in scripts where you only care about the exit code):
teamcity api /app/rest/builds/12345/tags/release -X POST --silent
Pagination
The TeamCity REST API returns paginated results for large collections. Use --paginate to automatically fetch all pages:
teamcity api /app/rest/builds --paginate
Combine paginated results into a single JSON array with --slurp:
teamcity api /app/rest/builds --paginate --slurp
Examples
# Get current user info
teamcity api /app/rest/users/current
# List all VCS roots
teamcity api /app/rest/vcs-roots
# Get build statistics
teamcity api /app/rest/builds/12345/statistics
# Trigger a build with parameters
teamcity api /app/rest/buildQueue -X POST \
--input <(echo '{"buildType":{"id":"MyBuild"},"properties":{"property":[{"name":"version","value":"1.0"}]}}')
# Download a specific artifact
teamcity api /app/rest/builds/12345/artifacts/content/report.html --raw > report.html
api flags
Flag
Description
-X, --method
HTTP method (GET, POST, PUT, DELETE, PATCH). Default: GET.
-f, --field
Add a body field as key=value. Builds a JSON object. Can be repeated.
-H, --header
Add a custom header. Can be repeated.
--input
Read request body from a file. Use - for stdin.
-i, --include
Include response headers in output
--raw
Output raw response without formatting
--silent
Suppress output on success
--paginate
Automatically fetch all pages
--slurp
Combine paginated results into a JSON array (requires --paginate)