A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The JFrog Artifactory API is how an app or AI agent works with a binary repository: deploying and downloading artifacts, creating and configuring repositories, searching with the Artifactory Query Language, and publishing and promoting builds. Access is granted through an access token that acts as a chosen user or group, and permission targets decide which repositories that identity can read, deploy to, or delete from. Artifactory keeps its methods at stable paths rather than dated versions, and can push events to a webhook when an artifact is deployed or deleted.
How an app or AI agent connects to JFrog Artifactory determines what it can reach. Calls go through a single REST surface, and an access token decides which repositories and actions are allowed.
The Artifactory REST API answers under the /artifactory path on the JFrog Platform host. Methods live at stable paths and are not pinned to a dated version. The newer Access API for tokens and permissions answers under /access and carries its own path version.
JFrog publishes an official MCP server that lets an agent call the JFrog Platform through the Model Context Protocol, covering repository management, build tracking, and AQL search. It runs as a remotely hosted server for JFrog SaaS, and the source can also be run locally from npm or the Docker image. The source is at github.com/jfrog/mcp-jfrog.
Webhooks deliver the chosen events, such as an artifact being deployed or deleted, to a receiver URL, so an integration is told when something changes rather than polling for it.
An access token is sent as a Bearer token in the Authorization header. It is scoped to a user or group and acts with that identity's permissions, and it can be made refreshable and given an expiry. JFrog recommends access tokens as the way to authenticate.
An identity token is an access token scoped to a single user's own permissions, generated from that user's profile. It is revoked automatically when the user is deleted or disabled.
Username and password can be sent with basic authentication. It is the simplest route but ties a call to a full account, so a scoped access token gives finer control.
API keys were a per-user key sent in the X-JFrog-Art-Api header. JFrog disabled the creation of new API keys from version 7.98 and directs new integrations to access tokens instead.
The Artifactory API is split into areas an agent can act on, such as repositories, artifacts, search, builds, and security. Each call needs a permission on the target repository, and some grant access to far more than others.
List repositories, read a repository's configuration, and create, update, or delete a local, remote, or virtual repository.
Deploy and download files, read an item's metadata and properties, and delete, copy, or move an artifact or folder.
Run an Artifactory Query Language search, find artifacts by name, search by group, artifact, and version coordinates, and search by property.
Publish build information, read a build, list all builds, promote a build between repositories, and delete a build.
Read a storage summary across the instance and read the storage details for a folder or file.
Create and read users and groups, read and create permission targets, and create and revoke access tokens.
Ping the instance, read its version, and check whether it is ready to serve requests.
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 | |
|---|---|---|---|---|---|---|
RepositoriesList repositories, read a repository's configuration, and create, update, or delete a local, remote, or virtual repository.5 | ||||||
| GET | /artifactory/api/repositories | List all repositories, optionally filtered by type and package. | read | Read | Current | |
Returns repositories the token can see. Listing and reading configuration generally needs admin or manage permission on the instance. Acts onrepository Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/repositories/{repoKey} | Get the configuration of a single repository. | read | Manage | Current | |
Reading repository configuration needs admin or manage permission on the repository, which is broader than the read permission used to download artifacts. Acts onrepository Permission (capability) ManageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /artifactory/api/repositories/{repoKey} | Create a local, remote, or virtual repository from a configuration body. | write | Admin | Current | |
Creating a repository is an administrative action that needs admin privileges, not a per-repository permission. Acts onrepository Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /artifactory/api/repositories/{repoKey} | Update an existing repository's configuration. | write | Admin | Current | |
Updating configuration needs admin privileges. Only the fields supplied in the body are changed. Acts onrepository Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /artifactory/api/repositories/{repoKey} | Delete a repository and all of the artifacts it holds. | write | Admin | Current | |
Deleting a repository removes its contents and needs admin privileges. There is no undo. Acts onrepository Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ArtifactsDeploy and download files, read an item's metadata and properties, and delete, copy, or move an artifact or folder.7 | ||||||
| PUT | /artifactory/{repoKey}/{itemPath} | Deploy a file to a repository at the given path. | write | Deploy | Current | |
The deploy permission, shown as deploy or cache in a permission target, lets a token upload to that repository. Acts onartifact Permission (capability) DeployVersionAvailable since the API’s base version Webhook event artifact-deployedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/{repoKey}/{itemPath} | Download an artifact from a repository. | read | Read | Current | |
The read permission lets a token download artifacts and read metadata from that repository. Acts onartifact Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/storage/{repoKey}/{itemPath} | Get an item's metadata, such as size, checksums, and last-modified time. | read | Read | Current | |
Reads file and folder information for a path the token can read. Acts onartifact Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/storage/{repoKey}/{itemPath}?properties | Read the custom properties attached to an item. | read | Read | Current | |
Properties are key-value labels on an item. Setting them, rather than reading them, needs the annotate permission. Acts onartifact Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /artifactory/{repoKey}/{itemPath} | Delete an artifact or a folder. | write | Delete | Current | |
The delete permission, shown as delete or overwrite in a permission target, lets a token remove or replace artifacts in that repository. Acts onartifact Permission (capability) DeleteVersionAvailable since the API’s base version Webhook event artifact-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /artifactory/api/copy/{srcRepoKey}/{srcPath}?to=/{targetRepoKey}/{targetPath} | Copy an artifact or folder to another path. | write | Deploy | Current | |
Copying needs read on the source and deploy on the target. A dry-run flag previews the result without changing anything. Acts onartifact Permission (capability) DeployVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /artifactory/api/move/{srcRepoKey}/{srcPath}?to=/{targetRepoKey}/{targetPath} | Move an artifact or folder to another path. | write | Delete | Current | |
Moving needs delete on the source, because it removes the original, and deploy on the target. Acts onartifact Permission (capability) DeleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchRun an Artifactory Query Language search, find artifacts by name, search by group, artifact, and version coordinates, and search by property.4 | ||||||
| POST | /artifactory/api/search/aql | Run an Artifactory Query Language search across items, builds, and properties. | read | Read | Current | |
Artifactory Query Language, AQL, is the flexible search language for Artifactory. Results are limited to items the token can read. On JFrog Cloud a heavy AQL query can be throttled with a 429. Acts onsearch result Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitThrottled by concurrency on JFrog Cloud SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/search/artifact | Search for artifacts by name, optionally within named repositories. | read | Read | Current | |
Returns only artifacts the token can read. Acts onsearch result Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/search/gavc | Search by Maven coordinates: group, artifact, version, and classifier. | read | Read | Current | |
GAVC is the group, artifact, version, and classifier naming used by Maven repositories. Returns only items the token can read. Acts onsearch result Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/search/prop | Search for items by their custom properties. | read | Read | Current | |
Matches items by key-value property and returns only items the token can read. Acts onsearch result Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BuildsPublish build information, read a build, list all builds, promote a build between repositories, and delete a build.5 | ||||||
| PUT | /artifactory/api/build | Publish build information for a build run. | write | Deploy | Current | |
Build information records the artifacts, dependencies, and environment of a build. Publishing needs deploy permission on the build. Acts onbuild Permission (capability) DeployVersionAvailable since the API’s base version Webhook event build-uploadedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/build/{buildName}/{buildNumber} | Get the published information for a specific build run. | read | Read | Current | |
Reads a build run the token has read permission on. Acts onbuild Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/build | List all builds known to the instance. | read | Read | Current | |
Returns the builds the token can read. Acts onbuild Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /artifactory/api/build/promote/{buildName}/{buildNumber} | Promote a build, optionally copying or moving its artifacts to a target repository. | write | Deploy | Current | |
Promotion can change a build's status and copy or move its artifacts, so it needs deploy on the build and on the target repository. Acts onbuild Permission (capability) DeployVersionAvailable since the API’s base version Webhook event build-promotedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /artifactory/api/build/{buildName} | Delete a build, specific runs of it, or all of its runs. | write | Delete | Current | |
Deleting build runs needs delete permission on the build. Acts onbuild Permission (capability) DeleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StorageRead a storage summary across the instance and read the storage details for a folder or file.2 | ||||||
| GET | /artifactory/api/storageinfo | Get a storage summary for the instance, including binaries, file store, and per-repository totals. | read | Admin | Current | |
The instance-wide storage summary needs admin privileges. Acts onstorage summary Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/storage/{repoKey}/{folderPath} | Read the storage details and contents of a folder or file. | read | Read | Current | |
Reads folder and file storage details for a path the token can read. Acts onstorage summary Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Security & accessCreate and read users and groups, read and create permission targets, and create and revoke access tokens.7 | ||||||
| PUT | /artifactory/api/security/users/{userName} | Create a user or replace an existing user. | write | Admin | Current | |
Managing users is an administrative action. Newer JFrog Platform instances also expose user management through the Access API. Acts onuser Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/security/users/{userName} | Get the details of a single user. | read | Admin | Current | |
Reading user details needs admin privileges. Acts onuser Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /artifactory/api/security/groups/{groupName} | Create a group or replace an existing group. | write | Admin | Current | |
Groups bundle users so a permission target can grant access to many people at once. Managing groups needs admin privileges. Acts ongroup Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/security/permissions | List the permission targets defined on the instance. | read | Admin | Current | |
A permission target binds repositories to users and groups with a set of permissions, such as read, deploy, annotate, delete, and manage. Reading them needs admin privileges. Acts onpermission target Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /artifactory/api/security/permissions/{permissionTargetName} | Create or replace a permission target. | write | Admin | Current | |
The body names the repositories and the users or groups, each with permissions chosen from read, deploy or cache, annotate, delete or overwrite, manage Xray metadata, and manage. This is the model Artifactory uses to scope access. Acts onpermission target Permission (capability) AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /access/api/v1/tokens | Create an access token, scoped to a user or group and optionally to specific resources. | write | Access admin | Current | |
Access tokens are issued by the Access service, which carries its own path version. A token's scope sets the identity and permissions it acts with. Creating a token for another identity needs admin privileges. Acts onaccess token Permission (capability) Access adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /access/api/v1/tokens/revoke | Revoke an access token by its token or reference value. | write | Access admin | Current | |
Revoking a token immediately stops it working. A token can revoke itself, and an admin can revoke any token. Acts onaccess token Permission (capability) Access adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SystemPing the instance, read its version, and check whether it is ready to serve requests.2 | ||||||
| GET | /artifactory/api/system/ping | Check that the instance is up, returning OK when it is healthy. | read | — | Current | |
A lightweight health check that needs no permission. Acts onsystem Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /artifactory/api/system/version | Get the Artifactory version and the add-ons enabled on the instance. | read | Read | Current | |
Reports the running version and license add-ons. Acts onsystem Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Artifactory can notify an app or AI agent when something happens, such as an artifact being deployed or deleted, instead of the app repeatedly asking. A webhook is configured for the chosen events, and Artifactory posts each event to the registered URL.
| Event | What it signals | Triggered by |
|---|---|---|
artifact deployed | Fires when an artifact is deployed to a watched repository. | /artifactory/{repoKey}/{itemPath} |
artifact deleted | Fires when an artifact is deleted from a watched repository. | /artifactory/{repoKey}/{itemPath} |
build uploaded | Fires when build information is published for a watched build. | /artifactory/api/build |
build promoted | Fires when a watched build is promoted. | /artifactory/api/build/promote/{buildName}/{buildNumber} |
JFrog Cloud bills on consumption, the storage and data transfer an account uses, rather than a fixed request quota, and protects itself with throttling that returns a clear status when a heavy query, such as a search, is over the limit.
Artifactory does not publish a fixed requests-per-hour quota the way some APIs do. JFrog Cloud bills on consumption, the combined storage and data transfer an account uses, measured in gigabytes, and relies on throttling and load balancing to protect the system rather than a declared per-second cap. The one clearly documented throttle is on search: on JFrog Cloud an Artifactory Query Language query is run against a concurrency limit, and a query that cannot get a slot within the configured timeout, ten seconds by default, returns a 429. A self-hosted instance can also be configured to rate-limit AQL.
Listing and search endpoints return results in pages, and large result sets are paged through with the offset and limit controls a given endpoint supports. An AQL query can set its own limit and offset in the query body, and folder and storage listings return child entries that an integration walks rather than fetching everything at once.
Deploys and downloads stream the file itself, so there is no small JSON payload cap on artifacts, and very large binaries are supported. Configuration and search bodies are JSON. A storage or search response that would be very large should be narrowed with a more specific query or paged.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request is malformed, such as an invalid configuration body or a search with missing parameters. The body holds an errors array, each entry with a status and a message. | Read the message in the errors array, correct the request, and resend. |
| 401 | Unauthorized | Authentication is missing or the credentials are invalid or expired. | Send a valid access token as a Bearer token in the Authorization header. |
| 403 | Forbidden | The token is valid but lacks the permission for this action, such as deploy or delete on the target repository, or admin for a configuration call. | Grant the missing permission on the repository's permission target, or use a token with the needed privileges. |
| 404 | Not Found | The repository, artifact, build, or other resource does not exist, or the token cannot see it. | Confirm the path and repository key, and that the token has read access to the resource. |
| 409 | Conflict | The request conflicts with the current state, such as deploying over an existing artifact when overwrite is not permitted. | Resolve the conflict, for example by granting overwrite or using a new path, then retry. |
| 429 | Too Many Requests | A throttling limit was hit. On JFrog Cloud a heavy search, such as an AQL query, is queued and returns 429 if it cannot get an execution slot within the timeout. | Slow down, reduce the query's load, or retry after a short wait. |
| 500 | Internal Server Error | The instance hit an unexpected error while handling the request. | Retry after a short wait, and check the instance's logs or status if it persists. |
The Artifactory REST API is not versioned by a dated string. Methods live at stable paths and change through Artifactory's continuous release train, while the newer Access API for tokens and permissions carries its own path version.
Artifactory ships on a continuous release train rather than versioning its REST API by a dated string. Methods stay at stable paths under /artifactory, and changes and deprecations are announced in the release notes ahead of removal. The token and permission work lives in the Access API, which carries its own path version such as /access/api/v1. Recent self-managed and SaaS releases sit in the 7.x line.
From June 2026 the Hugging Face repository layout is deprecated. New local and remote Hugging Face repositories use the new Machine Learning repository layout by default, and older repositories must be migrated before the cutover.
Following the API key deprecation that began at the end of 2024, the creation of new API keys is disabled from Artifactory version 7.98, and integrations are directed to access tokens. Support for Helm client versions below 3.0.0 was also removed in this window.
An integration calls stable paths and tracks deprecations through the release notes.
Artifactory release notes ↗Bollard AI sits between a team's AI agents and JFrog Artifactory. Grant each agent exactly the access it needs, read or write, repository by repository, and every call is checked and logged.