Deprecated JFrog APIs

JFrog APIs that have been deprecated are archived here until being decommissioned. Note: there will not be OpenAPI specification endpoints created for these legacy APIs. For an overview of available OpenAPI specification endpoints that are available, see OpenAPI Specifications.

Get Users (deprecated)

Description: Get the list of users.

Since: 2.4.0

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Security: Requires an admin user.

Usage: GET /artifactory/api/security/users

Produces: application/json (application/vnd.org.jfrog.artifactory.security.Users+json)

Sample Output:

GET /artifactory/api/security/users
[
  {
    "name": "davids"
    "uri" : "http://localhost:8082/artifactory/api/security/users/davids"
    "realm" : "internal"
  }, {
    "name": "danl"
    "uri" : "http://localhost:8082/artifactory/api/security/users/danl"
    "realm" : "ldap"
  }
]

To migrate to the new API:

• The response is no longer a bare JSON array. It is wrapped in { "users": [...], "cursor": "..." }.
• The key name is renamed to username in each user object.
• URIs are now relative, not absolute.
• Each item now includes a status field.
• Use the cursor and limit query parameters for pagination.

Get User Details (deprecated)

Description: Returns the details of an Artifactory user.

Since: 2.4.0

Security: Requires an admin user.

Usage: GET /artifactory/api/security/users/USERNAME

Produces: application/json (application/vnd.org.jfrog.artifactory.security.User+json)

Sample Output:

GET /artifactory/api/security/users/davids
{
  user.json
}

To migrate to the new API:

• The key name is renamed to username.
• All keys switch from camelCase to snake_case.
• The status enum value changes from uppercase to lowercase.
• The following fields are removed: lastLoggedInMillis, offlineMode, mfaStatus.

Create or Replace User (deprecated)

Description: Creates a new user in Artifactory or replaces an existing user.

Since: 2.4.0

Missing values will be set to the default values as defined by the consumed type.

Security: Requires an admin user

Usage: PUT /artifactory/api/security/users/USERNAME

Consumes: application/json (application/vnd.org.jfrog.artifactory.security.User+json)

Sample Usage:

PUT /artifactory/api/security/users/davids
{
  user.json
}

To migrate to the new API:

• The HTTP method changes from PUT to POST.
• The old API is create-or-replace; the new API is create-only.
• The username moves from the URL path to the request body (username field).
• All request body keys switch from camelCase to snake_case.

Update User (deprecated)

Description: Updates an existing user in Artifactory with the provided user details.

Since: 2.4.0

Missing values will be set to the default values as defined by the consumed type.

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Security: Requires an admin user.

Usage: POST /artifactory/api/security/users/USERNAME

Consumes: application/json (application/vnd.org.jfrog.artifactory.security.User+json)

Sample Usage:

POST /artifactory/api/security/users/davids
{
  user.json
}

To migrate to the new API:

• The HTTP method changes from POST to PATCH, enabling true partial updates.
• All request body keys switch from camelCase to snake_case.
• Group membership must be updated via a dedicated endpoint (PATCH /access/api/v2/groups/{name}/members) — it cannot be set through this endpoint.
• New fields available in the new API: resources_manager, manage_webhook.

Delete User (deprecated)

Description: Removes an Artifactory user.

Since: 2.4.0

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Security: Requires an admin user

Usage: DELETE /artifactory/api/security/users/USERNAME

Produces: application/text

Sample Usage:

DELETE /artifactory/api/security/users/davids

User 'davids' has been removed successfully.

To migrate to the new API:

• The path structure is aligned (DELETE /access/api/v2/users/{name}).
• The response changes from 200 OK with a text body to 204 No Content. Update your client to check the status code rather than the response body.

Expire Password for a Single User (deprecated)

Description: Expires a user's password.

Since: 4.4.2

Security: Requires an admin user.

Usage: POST /artifactory/api/security/users/authorization/expirePassword/USERNAME

Sample Usage:

POST /artifactory/api/security/users/authorization/expirePassword/davids

To migrate to the new API:

• The new path is POST /access/api/v2/users/USERNAME/password/expire.
• The new API returns 204 No Content with no response body.

Change Password (deprecated)

Description: Changes a user's password.

Since: 4.4.2

Security: Admin can apply this method to all users, and each (non-anonymous) user can use this method to change their own password.

Usage: POST /artifactory/api/security/users/authorization/changePassword -H "Content-type: application/json" -d ' { "userName" : "{user}", "oldPassword" : "{old password}", "newPassword1" : "{new password}", "newPassword2" : "{verify new password}" }

Produces: application/text

Sample Usage:

POST /artifactory/api/security/users/authorization/changePassword -H "Content-type: application/json" -d '{ "userName" : "davids", "oldPassword" : "op", "newPassword1" : "np", "newPassword2" : "np" }'

To migrate to the new API:

• The HTTP method changes from POST to PUT.
• The new path is PUT /access/api/v2/users/USERNAME/password — the username is now part of the URL path.
• The request body is simplified to contain only the new password field; authentication uses an identity token.
• The response changes to 204 No Content.

Unlock Locked Out User (deprecated)

Description: Unlocks a single user who was locked out due to recurrent incorrect login attempts.

Security: Requires a valid admin user

Usage: POST /artifactory/api/security/unlockUsers/USERNAME

Produces: application/text

Since: 4.4

Sample Usage:

POST /artifactory/api/security/unlockUsers/USERNAME

To migrate to the new API:

• The new path is POST /access/api/v2/users/USERNAME/unlock.
• The response changes to 204 No Content.

Get Groups (deprecated)

Description: Get the groups list.

Since: 2.4.0

Security: Requires an admin user

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Usage: GET /artifactory/api/security/groups

Produces: application/json (application/vnd.org .jfrog.artifactory.security.Users+json) , application/json (application/vnd.org.jfrog.artifactory.security.Groups+json), application/json (application/vnd.org.jfrog.artifactory.security.PermissionTargets+json)

Sample Output:

GET /artifactory/api/security/groups
[
  {
    "name": "readers"
    "uri" : "http://localhost:8081/artifactory/api/security/groups/readers"
  }, {
    "name": "tech-leads"
    "uri" : "http://localhost:8081/artifactory/api/security/groups/tech-leads"
  }
]

To migrate to the new API:

• The response is no longer a bare JSON array. It is wrapped in { "groups": [...], "cursor": "..." }.
• The key name is renamed to group_name in each group object.
• Use the cursor and limit query parameters for pagination.

Get Group Details (deprecated)

Description: Get the details of an Artifactory Group

Since: 2.4.0

From Artifactory version 6.13, you can use the includeUsers parameter (includeUsers=true) to get the users' details.

Security: Requires an admin user

Usage: GET /artifactory/api/security/groups/{groupName}

Produces: application/json (application/vnd.org .jfrog.artifactory.security.Group+json)

Sample Output:

GET /artifactory/api/security/groups/dev-leads
{
group.json
}

To migrate to the new API:

• All keys switch from camelCase to snake_case.
• userNames is renamed to members and is always returned.
• New fields available in the new API: manage_resources, manage_webhook.

Create or Replace Group (deprecated)

Description: Creates a new group in Artifactory or replaces an existing group

Since: 2.4.0

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Security: Requires an admin user

Usage: PUT /artifactory/api/security/groups/{groupName}

Consumes: application/json (application/vnd.org.jfrog.artifactory.security.Group+json)

Sample Usage:

PUT /artifactory/api/security/groups
{
group.json
}

To migrate to the new API:

• The HTTP method changes from PUT to POST.
• The old API is create-or-replace; the new API is create-only. Use PATCH /access/api/v2/groups/{name} to update.
• The group name moves from the URL path to the request body (name field).
• All keys switch from camelCase to snake_case.
• userNames is renamed to members for initial group members.
• New fields: manage_resources, manage_webhook.
• The response changes from 201 Created with an empty body to 201 Created with the full GroupResponse JSON.

Update Group (deprecated)

Description: Updates an existing group in Artifactory with the provided group details.

Since: 2.4.0

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

From Artifactory 7.15.3, you can enforce using lower-case characters in user names when associating users to groups by setting the validate.lowercase.username.on.groupto true. The default is set to
false. When set to true, an error will be generated if an upper-case character is used in a user name.

Security: Requires an admin user

Usage: POST /artifactory/api/security/groups/{groupName}

Consumes: application/json (application/vnd.org.jfrog.artifactory.security.Group+json)

Sample Usage:

POST /artifactory/api/security/groups/dev-leads
{
group.json
}

To migrate to the new API:

• The HTTP method changes from POST to PATCH, enabling true partial updates.
• All keys switch from camelCase to snake_case.
• Group members cannot be updated via this endpoint — use PATCH /access/api/v2/groups/{name}/members instead.
• New updatable fields: manage_resources, manage_webhook.
• The response changes from 200 OK with no body to the full GroupResponse JSON.
• All fields in the request are nullable/optional (true PATCH semantics).

Delete Group (deprecated)

Description: Removes an Artifactory group.

Since: 2.4.0

To support spaces in the User, Group, or Permission names, a plus symbol ('+') is automatically placed when there is a space. This is set by default because the property artifactory.security.api.plus.insteadof.space is set to true. If you want to use the plus symbol ('+'), set artifactory.security.api.plus.insteadof.space to false.

Security: Requires an admin user

Usage: DELETE /artifactory/api/security/groups/{groupName}

Produces: application/text

Sample Usage:

DELETE /artifactory/api/security/groups/dev-leads

Group 'dev-leads' has been removed successfully.

To migrate to the new API:

• The path structure is similar (DELETE /access/api/v2/groups/{name}).
• The response changes from 200 OK with a confirmation message to 204 No Content. Update your client to check the status code rather than the response body.

Get Tokens (deprecated)

Description: Get a list of all tokens created by an Artifactory instance

Since: 5.0.0

Security: Requires an admin user.

Usage: GET /artifactory/api/security/token

Content-Type: application/x-www-form-urlencoded

Produces: application/json

{
  "tokens":[
    {
      "token_id":"<the token id>",
      "issuer":"<the service ID of the issuing Artifactory instance>",
      "subject":"<subject>",
      "expiry": <time when token expires as seconds since 00:00:00 1/1/1970>,
      "refreshable":<true | false>,
      "issued_at":<time issued as seconds since 00:00:00 1/1/1970>,
    }, ...
  ]
}

Sample Usage:

curl -uadmin:password -XGET "http://localhost:8082/artifactory/api/security/token

 
200 OK
{
  "tokens":[
    {
      "token_id":"123",
      "issuer":"jf-artifactory@123123",
      "subject":"jf-artifactory@123123/users/theusername",
      "expiry":145154545,
      "refreshable":true,
      "issued_at":144152345
    }, ...
  ]
}

To migrate to the new API:

• The new endpoint is GET /access/api/v1/tokens.
• Access supports query parameters for filtering and sorting; the old Artifactory endpoint has no filtering.
• Additional token fields in the Access response: audience, description, scope, project_key, last_used.
• Both APIs return a tokens array wrapper.
• Time fields (issued_at, expiry) are epoch seconds in both APIs.

Revoke Token (deprecated)

Description: Revoke an access token by specifying the token or the token_id.

Since: 5.0.0

Security: Requires an admin user.

Usage: POST /artifactory/api/security/token/revoke

Content-Type: application/x-www-form-urlencoded

Produces: application/json

Sample Usage:

curl -uadmin:password -XPOST "http://localhost:8082/artifactory/api/security/token/revoke" -d "token=fasdt3..."
or
curl -uadmin:password -XPOST "http://localhost:8082/artifactory/api/security/token/revoke" -d "token_id=7e0eec..."
 
200 OK (Also returned if the token was already revoked or non-existent)
 
400 (Error) If the token was created by a different Artifactory instance (and hence cannot be revoked)

This endpoint can take either of the following parameters:

To migrate to the new API:

• The HTTP method changes from POST to DELETE.
• Access splits revocation into two endpoints: revoke by token ID (DELETE /access/api/v1/tokens/{token_id}) and revoke by token value (DELETE /access/api/v1/tokens/revoke).
• The old token_type_hint parameter has no equivalent in Access.
• The old API returns a text message ("Token revoked"); Access returns 200 with an empty body or JSON containing revoked_token_id.

Save Security Configuration (deprecated)

Description: Saves the security configuration (security.xml). Requires the security.xml file from the same version.

Since: From Artifactory 2.2.0 - 6.x.

Security: Requires a valid admin user

Usage: POST /artifactory/api/system/security

Consumes: application/xml

Sample Usage:

POST /artifactory/api/system/security

<security.xml/>

Expire Password for All Users (deprecated)

Description: Expires a password for all users.

Since: 4.4.2

Security: Requires an admin user.

Usage: POST /artifactory/api/security/users/authorization/expirePasswordForAllUsers

Sample Request:

POST https://[JFrogPlatformURL]/artifactory/api/security/users/authorization/expirePasswordForAllUsers

To migrate to the new API:

• The new path uses snake_case: POST /access/api/v2/users/expire_password_for_all_users.
• The new API returns 200 with a confirmation message.

Get Permission Targets (deprecated)

Description: Returns the permission targets list. Manages permissions on repositories only. For permissions on builds and release bundles, use the V2 API at /v2/security/permissions.

Since: 2.4.0

Security: Requires an admin user.

Usage: GET /artifactory/api/security/permissions

Produces: application/json

Sample Output:

GET /artifactory/api/security/permissions
[
  {
    "name": "Anything",
    "uri": "http://localhost:8081/artifactory/api/security/permissions/Anything"
  }
]

To migrate to the new API:

• The response is no longer a bare JSON array. It is wrapped in { "permissions": [...], "cursor": "..." }.
• URIs are now relative, not absolute.
• Use the cursor and limit query parameters for pagination.

Get Permission Target Details (deprecated)

Description: Returns the details of an Artifactory permission target. Manages permissions on repositories only. For permissions on builds and release bundles, use the V2 API at /v2/security/permissions/{permissionTargetName}.

Since: 2.4.0

Security: Requires an admin user.

Usage: GET /artifactory/api/security/permissions/{permissionTargetName}

Produces: application/json (application/vnd.org.jfrog.artifactory.security.PermissionTarget+json)

Sample Output:

GET /artifactory/api/security/permissions/Any
{
  "name": "Any",
  "repositories": ["ANY"]
}

To migrate to the new API:

• The JSON structure is completely different. The v1 model is flat; the Access v2 model uses nested resources.
• V1 uses short backend codes for actions (r, w, m); Access v2 uses uppercase enum names (READ, WRITE, MANAGE).
• Organize repositories under resources.{type}.targets.{repoKey} with per-target patterns and actions.
• Access v2 adds the fields description, created_by, and modified_by.
• Access v2 includes artifact, build, and release bundle resource types in a single response.

Create or Replace Permission Target (deprecated)

Description: Creates a new permission target in Artifactory or replaces an existing one. Manages permissions on repositories only.

Since: 2.4.0

Security: Requires an admin user.

Usage: PUT /artifactory/api/security/permissions/{permissionTargetName}

Consumes: application/json (application/vnd.org.jfrog.artifactory.security.PermissionTarget+json)

Sample Usage:

PUT /artifactory/api/security/permissions/my-perm
{
  "name": "my-perm",
  ...
}

To migrate to the new API:

• The HTTP method changes from PUT to POST.
• The old API is create-or-replace; the new API is create-only.
• The permission name moves from the URL path to the request body (name field).
• Use the nested resources structure for the request body (see Get Permission Target Details migration steps above for schema details).

Delete Permission Target (deprecated)

Description: Deletes an Artifactory permission target.

Since: 2.4.0

Security: Requires an admin user.

Usage: DELETE /artifactory/api/security/permissions/{permissionTargetName}

Produces: application/text

Sample Usage:

DELETE /artifactory/api/security/permissions/my-perm

Response: 200 OK

To migrate to the new API:

• The path structure is the same (DELETE /access/api/v2/permissions/{name}).
• The response changes from 200 OK with a text message to 204 No Content. Update your client to check the status code rather than the response body.

Get Password Expiration Policy (deprecated)

Description: Returns the password expiration policy.

Since: 4.4.2

Security: Requires an admin user.

Usage: GET /artifactory/api/security/configuration/passwordExpirationPolicy

Produces: application/json

Sample Output:

GET /artifactory/api/security/configuration/passwordExpirationPolicy
{
  "enabled": "true",
  "passwordMaxAge": "60",
  "notifyByEmail": "true"
}

To migrate to the new API:

• The new endpoint is GET /access/api/v1/config/security/user_lock_policy.
• Password expiry is embedded in the user lock policy: map enabled to passwordExpiryDays > 0, and passwordMaxAge to passwordExpiryDays.
• The notifyByEmail field is not exposed in the new API.

Set Password Expiration Policy (deprecated)

Description: Sets the password expiration policy.

Since: 4.4.2

Security: Requires an admin user.

Usage: PUT /artifactory/api/security/configuration/passwordExpirationPolicy

Consumes: application/json

Sample Usage:

PUT /artifactory/api/security/configuration/passwordExpirationPolicy
{
  "enabled": "true",
  "passwordMaxAge": "60",
  "notifyByEmail": "true"
}

To migrate to the new API:

• The new endpoint is PUT /access/api/v1/config/security/user_lock_policy.
• Send the full UserLockPolicyConfig body to avoid overwriting unrelated fields.
• Map enabled + passwordMaxAge to passwordExpiryDays (where enabled=true corresponds to passwordExpiryDays > 0).

Remote Repository Configuration (deprecated)

Description: Returns the shared configuration of a remote repository.

Since: 2.2.0

Security: Requires a valid user for a shared remote repository and admin user for anything else. Shared remote repository data will be sanitized for security when non-admin user is used.

Usage: GET /artifactory/api/repositories/{remoteRepoName}/configuration

Produces: application/json (application/vnd.org.jfrog.artifactory.repositories.SharedRemoteRepositoryConfiguration+json)

Sample Output:

GET /artifactory/api/repositories/remote-repo/configuration

{
repository-config.json
}

Folder Sync (deprecated)

Description: Triggers a no-content download of artifacts from a remote Artifactory repository for all artifacts under the specified remote folder. Can optionally delete local files if they do not exist in the remote folder, overwrite local files only if they are older than remote files, or never overwrite local files.

The default is not to delete any local files and to overwrite older local files with remote ones. By default progress marks of the sync are displayed. The default timeout for the remote file list is 15000 milliseconds (15 seconds).

Security: Requires a privileged user (can be anonymous). For non-admin users will replicate at max the number of files as defined by the artifactory.search.userQueryLimit system property.

Usage: GET artifactory/api/sync/{remoteRepositoryKey}/{folderPath}[?progress=showProgress][&mark=numOfBytesToPrintANewProgressMark][&delete=deleteExistingFiles][&overwrite=never/force][&timeout=fileListTimeoutInMillis]

Produces: text/plain

Since: 2.2.4

Sample Output:

GET artifactory/api/sync/my-remote/org/acme/1.0?progress=1&delete=1
.....................................................
.....................................................
.....................................................
..........................................

Completed: 970/1702 bytes
.....................................................
..................
Completed: 1702/1702 bytes
Completed with 0 errors and 2 warnings (please check the server log for more details).

File Compliance Info (deprecated)

Description: Get compliance info for a given artifact path. The result includes license and vulnerabilities if any. Supported by local and local-cached repositories.

Since: 3.0.0

Security: Requires an authenticated user.

Usage: GET: artifactory/api/compliance/{repoKey}/{item-path}

Produces: application/json

Sample Output:

GET: artifactory/api/compliance/libs-release-local/ch/qos/logback/logback-classic/0.9.9/logback-classic-0.9.9.jar
{
  "licenses" : [ {"name":"LGPL v3", "url": "http://"}, {"name":"APL v2", "url": "http://"}... ],
  "vulnerabilities" : [ {"name":"CVE-13427", "url": "http://"}, {"name":"CVE-1041", "url": "http://"}...  ]
}

Pull/Push Replication (deprecated)

Description: Schedules immediate content replication between two Artifactory instances. Replication can include properties and can optionally delete local items if they do not exist in the source repository.

This API completes the existing cron-based replication exposed via the Artifactory UI and allows for on-demand execution.

• Pull Replication: Pulls content from a remote Artifactory repository to a local cache of the remote repository.
• Push Replication: Pushes content from a local repository into a remote Artifactory local repository.

Supported by local, local-cached, and remote repositories.

Notes: Requires Artifactory Pro

Security: Requires a privileged user (can be anonymous) For non-admin users, will replicate at max the number of files as defined by the artifactory.search.userQueryLimit system property.

Usage: POST /api/replication/{srcRepoKey}/{srcPath}

Consumes: application/json (application/vnd.org.jfrog.artifactory.replication.ReplicationRequest+json)

Since: 2.4.0

Sample Usage:

POST /api/replication/libs-release-local/com/acme
{
  //The following is only applicable for push replication
  + "url" : "https://repo.nmiy.org/repo-key", // The remote repository URL
  + "username": "replicator", //The name of a user with deploy permissions on the remote repository
  + "password": "***", //The remote repository password
  - "properties": true, //Sync item properties (true by default)
  - "delete": true, //Sync deletions (false by default)
  - "proxy": "org-prox", //A name of an Artifactory-configured proxy to use for remote requests
}

Export Component Details V1 (deprecated)

Description: Export component scan results, SPDX SBOM doc or CycloneDX SBOM doc.

Security: Requires a valid user with the "Read" permission.

Usage: POST /xray/api/v1/component/exportDetails

Consumes: application/json

Produces: application/octet-stream

Request Body:

Sample Request exporting the scan results:

{
 "package_type": "docker",
 "sha_256": "1d36301476dc57eb479e03d9e37a885dd751a6e6979f6f916a92c10cb7520e4e",
 "component_name": "ics:latest",

 "violations": true,
 "include_ignored_violations": true,            
 "license": true,
 "exclude_unknown": false,
 "operational_risk": true,
 "security": true,
 "secrets": true,
 "services": true,
 "applications": true,
  "output_format": "pdf"
}

Sample Request - exporting CycloneDX Doc:

{
 "package_type": "docker",  
 "component_name": "ics:latest",
 "sha_256": "1d36301476dc57eb479e03d9e37a885dd751a6e6979f6f916a92c10cb7520e4e",

 "cyclonedx": true,
 "cyclonedx_format": "json",
 "vex": false
}

Sample Request - exporting SPDX and CycloneDX JSON Docs:

{
 "package_type": "maven",
 "component_name": "org.eclipse.jdt:ecj:3.12.3",
 
 "spdx": true,
 "spdx_format": "json",
 "cyclonedx": true,
 "cyclonedx_format": "json",
 "vex": false
}

Response Codes

Metadata GraphQL API (deprecated)

Metadata GraphQL API includes the following:

• Authentication to Use the Metadata Server GraphQL
• GraphiQL
• Build a Metadata GraphQL Query

Authentication to Use the Metadata Server GraphQL

Using GraphQL to query metadata provides a simple way to fetch packages data stored in the metadata microservice. Since GraphQL enables you to query objects in a hierarchical structure, and allows you to choose which fields to include in a response, it will be simpler to find the exact data you are looking for.

To use the metadata server GraphQL, you will need a scoped token for Artifactory.

cURL Example

curl -H "Authorization: Bearer <Your Token>" -XPOST http://<server:port>/metadata/api/v1/query -d '{"query":"..." }'

GraphiQL

JFrog offers a version of a simple GraphiQL, a UI tool for your GraphQL queries. You can use the GraphiQL to learn about the GraphQL metadata schema and as a playground to test your queries. To access it, <your server url>/metadata/api/v1/query/graphiql.
.

Build a Metadata GraphQL Query

In this section, you will learn about the structure of a query, how to construct a query, and the available Metadata queries. It includes the following sections:

• GraphQL Pagination
• Available Queries for Metadata GraphQL
• Filter Types
• Entities and Fields
• Example 1: Package by Name and Type
• Example 2: Package with its Versions and Licenses by Creation Date

GraphQL Pagination

The Metadata GraphQL implementation utilizies GraphQL's pagination convention using the GraphQL connection model. This means that every entity queried is embedded within a wrapper containing the pagination information. To learn more, see Pagination and edges.

GraphQL query enables you to sort and order your queries by using a set of predefined arguments. Available sort arguments are First (limit), After (Offset) and OrderBy.

For example, for Package pagination you can use: (first:5 after:$PackageCursor). The Package cursor is retrieved from the last Package queried. Additionally, you can get the last Package cursor and know if there are additional Packages to query by adding the pageInfo to your query.

Pagination Example

query
{
  packages (
    # filter argument
    filter: {name: "*" },
    first: 5,
    after: "UGFja2FnZTo1"
  )
  {
   pageInfo 
    { 
    hasNextPage  
    endCursor
  }
    # Connection Model
    edges {
      cursor
      node {
        #Object fields to be returned by the query  
        name
        packageType
        description
        }
      }
    } 
}

Available Queries for Metadata GraphQL

The following are the queries available for the Metadata GraphQL.

Packages

packages(
filter: PackageFilter!
first: Int
after: ID
orderBy: PackageOrder
): PackageConnection!

Versions

versions( 
filter: VersionFilter! 
first: Int 
after: ID 
orderBy: VersionOrder 
): VersionConnection!

Files

files( 
filter: FileFilter! 
first: Int 
after: ID 
orderBy: FileOrder 
): FileConnection!

Filter Types

The following describes the available filter names you can use to construct a filter for each of the query types.

PackageFilter!

VersionFilter!

FileFilter!

Entities and Fields

Package

Licenses

Properties

Qualifiers

Versions

Sources

PackageStats

VersionVulnerabilities

Files

VersionRepository

VersionStats

VersionContributor

Example 1: Package by name and type

Query

# Query package name and description, filtered by name pattern, ordered by name descending
query {
    packages(
        filter: {
            name: "*ello*",
            packageTypeIn: [NPM, DOCKER]
        },
        first: 3,
        orderBy: {
            field: NAME,
            direction: DESC
        }
    ) {
        edges {
            node {
                name
                description 
            }
        }
    }
}

Sample Result

{
  "data": {
    "packages": {
      "edges": [
        {
          "node": {
            "name": "p2Hello",
            "description": "Sample Package 2"
          }
        },
        {
          "node": {
            "name": "p1Hello",
            "description": "Sample Package 1"
          }
        },
        {
          "node": {
            "name": "library/hello-world",
            "description": null
          }
        }
      ]
    }
  }
}

Example 2: Package with its Versions and Licenses by Creation Date

Query

# Query Package name description and creation date, with its version names and sizes, and associated licenses name and source for each version. 
# filtered by package creation date, limited to first 3 results.
query {
    packages(
        filter: {
            createdMin: "2020-01-01T01:59:00.000Z"
        },
        first: 3
      ) 
    {
        edges {
            node {
                name
                description 
                created
                versions{
                    name
                    size
                    licenses{
                        name
                        source
                    }
                }
            }
        }
    }
}

Sample Result

{
  "data": {
    "packages": {
      "edges": [
        {
          "node": {
            "name": "sample_rpm-1",
            "description": "Sample RPM Package for data generation",
            "created": "2020-01-05T09:53:21.588Z",
            "versions": [
              {
                "name": "0:2.0.0-2.0.0",
                "size": "2080",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              },
              {
                "name": "0:8.0.0-8.0.0",
                "size": "2080",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        },
        {
          "node": {
            "name": "example package 7",
            "description": null,
            "created": "2020-01-09T18:02:48.604Z",
            "versions": [
              {
                "name": "0.4.6",
                "size": "",
                "licenses": [
                  {
                    "name": "Apache-2.0",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        },
        {
          "node": {
            "name": "another example",
            "description": "a nice package for web apps",
            "created": "2020-01-05T17:43:13.979Z",
            "versions": [
              {
                "name": "1.2.32",
                "size": "",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              },
              {
                "name": "1.7.9",
                "size": "623646",
                "licenses": [
                  {
                    "name": "MIT",
                    "source": "Local File"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}