A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Jenkins API is how an app or AI agent works with a Jenkins controller: reading a job and its builds, triggering a build with or without parameters, fetching console output, and creating, copying, or deleting jobs. Access is granted through a Jenkins user account and an API token sent over HTTP Basic authentication, and that account's matrix or role permissions are the boundary on everything it can do, since Jenkins has no per-endpoint scopes. The API has no version number of its own, and each controller reports its Jenkins release in a response header.
How an app or AI agent connects to Jenkins determines what it can reach. There are several routes, each tied to a Jenkins user account and the matrix or role permissions that account carries.
Jenkins exposes a remote access API by appending /api/ to almost any controller, job, or build URL. The same resource is available as JSON, XML, or a Python-compatible variant, and the tree and depth query parameters trim or expand the data returned.
The Jenkins community ships a first-party MCP Server plugin, jenkinsci/mcp-server-plugin, that lets an AI assistant call Jenkins through the Model Context Protocol. It implements MCP spec 2025-06-18 and exposes tools such as getJob, getJobs, triggerBuild, getBuild, and getBuildLog. The streamable HTTP endpoint is /mcp-server/mcp on the controller, and it authenticates with a Jenkins user and API token.
Jenkins core does not push events, but plugins such as the Notification plugin post a JSON payload to a receiver URL when a build starts or finishes, so an app does not have to poll for the latest result.
An API token is generated on a Jenkins user's account page and sent with that username over HTTP Basic authentication. It carries the same permissions as the user, and unlike a password it is exempt from CSRF crumb checks, which makes it the recommended choice for scripts and automation.
HTTP Basic authentication with a username and password also works, but password requests are subject to CSRF protection and so need a crumb on every POST. An API token avoids that and never exposes the account password.
The Jenkins API is organised around the things a controller manages, such as jobs, builds, the build queue, agent computers, plugins, and views. What an agent can do in each area is decided by the permissions on the user account it authenticates as, not by per-method scopes.
Read a job's details, trigger a build with or without parameters, read and update a job's config.xml, and create, copy, delete, enable, or disable a job.
Read details and console output for a specific build, and read the most recent build of a job.
Read the items waiting in the build queue and cancel a queued item before it starts.
Read the controller and its build agents, the executor state, and the details of a single node.
Read top-level controller information, list installed plugins, and fetch a CSRF crumb.
Read the jobs grouped inside a view on the Jenkins dashboard.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
JobsRead a job's details, trigger a build with or without parameters, read and update a job's config.xml, and create, copy, delete, enable, or disable a job.10 | ||||||
| GET | /job/{name}/api/json | Get a job's details, including its builds, health, and parameters. | read | — | Current | |
Appending /api/json, /api/xml, or /api/python to a job URL returns it in that format. The depth and tree query parameters control how much nested data is returned. Permission: Job/Read. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/build | Trigger a new build of a job. | write | — | Current | |
On a multibranch pipeline or organization folder this triggers a scan instead. Username and API token authentication is exempt from CSRF, so no crumb is needed. Permission: Job/Build. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/buildWithParameters | Trigger a build of a parameterized job, passing string or file parameters. | write | — | Current | |
Parameters are sent as form fields; file parameters use a multipart form. Permission: Job/Build. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /job/{name}/config.xml | Fetch a job's full configuration as XML. | read | — | Current | |
The config.xml is the job's complete definition, often used as a template for creating other jobs. Permission: Job/ExtendedRead (or Job/Configure). Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/config.xml | Replace a job's configuration by posting a new config.xml. | write | — | Current | |
The request body is the full XML configuration, sent with an XML content type. Permission: Job/Configure. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /createItem | Create a job from a posted config.xml, named by the name query parameter. | write | — | Current | |
Called as /createItem?name={job}. Inside a folder the path is prefixed with that folder, such as /job/{folder}/createItem. Permission: Job/Create. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /createItem | Copy an existing job into a new one. | write | — | Current | |
Called as /createItem?name={new}&mode=copy&from={existing}. The from parameter applies only when mode is copy. Permission: Job/Create. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/doDelete | Delete a job and its build history. | write | — | Current | |
Deletion is permanent and removes the job's recorded builds. Permission: Job/Delete. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/enable | Enable a disabled job so it can run again. | write | — | Current | |
Permission: Job/Configure. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /job/{name}/disable | Disable a job so it cannot be triggered. | write | — | Current | |
A disabled job stays configured but will not start builds until enabled. Permission: Job/Configure. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BuildsRead details and console output for a specific build, and read the most recent build of a job.3 | ||||||
| GET | /job/{name}/{number}/api/json | Get the details of a specific build by its number. | read | — | Current | |
Aliases such as lastBuild, lastSuccessfulBuild, and lastStableBuild can be used in place of a number. Permission: Job/Read. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /job/{name}/lastBuild/api/json | Get the details of a job's most recent build. | read | — | Current | |
Other aliases include lastSuccessfulBuild and lastFailedBuild. Permission: Job/Read. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /job/{name}/{number}/consoleText | Fetch the plain-text console output of a build. | read | — | Current | |
Console output can contain secrets, file paths, and environment data printed during the build. Permission: Job/Read. Acts onbuild Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Build queueRead the items waiting in the build queue and cancel a queued item before it starts.2 | ||||||
| GET | /queue/api/json | List the items currently waiting in the build queue. | read | — | Current | |
Each queue item carries an id that can be used to query or cancel it. Permission: Overall/Read. Acts onqueue item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /queue/cancelItem | Cancel a queued item before it starts running. | write | — | Current | |
Called as /queue/cancelItem?id={id} with the queue item id. Permission: Job/Cancel. Acts onqueue item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Computers & nodesRead the controller and its build agents, the executor state, and the details of a single node.2 | ||||||
| GET | /computer/api/json | List the controller and its build agents, with executor and offline state. | read | — | Current | |
The set of computers shown depends on the calling user's node permissions. Permission: Agent/Connect (read of the node list). Acts oncomputer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /computer/{name}/api/json | Get the details of a single build node. | read | — | Current | |
The built-in controller node is addressed as (built-in), URL-encoded in the path. Permission: Agent/Connect. Acts oncomputer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
System & pluginsRead top-level controller information, list installed plugins, and fetch a CSRF crumb.3 | ||||||
| GET | /api/json | Get top-level controller information, including its jobs, views, and node mode. | read | — | Current | |
The X-Jenkins response header on this and any page reports the controller's version. Permission: Overall/Read. Acts oncontroller Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pluginManager/api/json | List the plugins installed on the controller. | read | — | Current | |
Use the depth parameter to include each plugin's version and enabled state. Reading the plugin manager requires administrator access. Permission: Overall/Administer. Acts onplugin Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /crumbIssuer/api/json | Fetch a CSRF crumb for use on later POST requests. | read | — | Current | |
The crumb is sent on later POSTs in the Jenkins-Crumb header. Requests authenticated with an API token are exempt from CSRF and do not need a crumb. Permission: Overall/Read. Acts oncrumb Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ViewsRead the jobs grouped inside a view on the Jenkins dashboard.1 | ||||||
| GET | /view/{name}/api/json | Get a view and the jobs grouped inside it. | read | — | Current | |
A view is a saved grouping of jobs shown as a tab on the dashboard. Permission: View/Read. Acts onview Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Jenkins core does not push events on its own. With a notification plugin installed, Jenkins can post a payload to a receiver URL when a build starts or finishes, instead of an app repeatedly asking for the latest build.
| Event | What it signals | Triggered by |
|---|
Jenkins is self-hosted, so it sets no fixed request quota by default. How fast an app or AI agent can call is bounded by the controller's own capacity and any reverse proxy or plugin limits an administrator adds.
Jenkins is self-hosted and applies no built-in request quota or rate limit by default. How fast an app or AI agent can call is set by the controller's own hardware and configuration, and by any reverse proxy, load balancer, or plugin an administrator places in front of it. Heavy polling of large jobs is best narrowed with the tree query parameter so each response carries only the needed fields, which lowers the load a controller has to handle.
The API does not paginate in the usual page-by-page sense. A list resource, such as a job's builds or the queue, returns its items in one response, and the depth parameter pulls in nested objects while the tree parameter selects exactly which fields and sub-fields come back. Build history can be sliced with range syntax such as builds[0,10] inside a tree expression.
There is no fixed payload size limit defined by the API itself. A deep request, made with a high depth value, can return a very large document, so the tree parameter is the recommended way to keep responses small. Console output is returned in full as plain text and can be large for long builds.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or invalid. The username and API token were not supplied or were rejected. | Send the username and a valid API token over HTTP Basic authentication. |
| 403 | Forbidden | The account is authenticated but lacks the permission for this action, or a POST was made without a valid CSRF crumb when using password authentication. | Grant the user the needed permission in the security matrix, or use an API token, which is exempt from the crumb requirement. |
| 404 | Not Found | The job, build, node, or view in the path does not exist, or the account cannot see it. | Confirm the item name and path, remembering that jobs inside a folder are addressed as /job/{folder}/job/{name}. |
| 500 | Internal Server Error | The controller hit an error handling the request, sometimes returned as an HTML stack trace rather than JSON. | Check the controller's system log for the cause, then retry once the underlying issue is fixed. |
The Jenkins remote access API has no version number in its paths. Each Jenkins controller reports its own release in the X-Jenkins response header, and the API tracks whatever that release exposes.
The Jenkins remote access API has no version number. Each controller runs a specific Jenkins weekly or LTS release and reports it in the X-Jenkins response header, and the API reflects whatever that release and its installed plugins expose. The notable dated changes below come from the security and tooling around the API rather than from a versioned API surface.
The Jenkins community released the MCP Server plugin, which turns a controller into a Model Context Protocol server for AI assistants. It implements MCP spec 2025-06-18, recommends the streamable HTTP transport at /mcp-server/mcp, and exposes tools such as getJob, getJobs, triggerBuild, getBuild, and getBuildLog, all authenticated with a username and API token.
From this period Jenkins reworked API tokens so they are generated and revoked independently of the account password, and tightened CSRF protection, with API token requests treated as exempt from the crumb requirement. This made a user-plus-API-token the recommended credential for the remote access API over username and password.
An integration reads the X-Jenkins header to learn the controller's release rather than pinning an API version.
Jenkins changelog ↗Bollard AI sits between a team's AI agents and Jenkins. Grant each agent exactly the access it needs, read or write, job by job, and every call is checked and logged.