Stored Packages OneModel GraphQL

Metadata records provide comprehensive information about software packages, versions, and artifacts stored in JFrog Artifactory. The Metadata service enables you to query package information, track versions, analyze artifacts, and manage your software supply chain through a powerful GraphQL API.

GraphQL API

The Metadata service uses OneModel/GraphQL to perform the following operations:

• Get Package: Returns a single, specific package by name and type.
• Search Packages: Search for packages with advanced filtering, ordering, and pagination.
• Search Package Versions: Search for package versions with filtering by version properties, tags, dates, and more.
• Search Package Artifacts: Search for artifacts (files) by checksum, name, size, and other properties.

Get Package

Description: Returns the requested data for a single, known package based on its name and type. Use the getPackage query when you know the exact package identifier and want that package's data.

To find packages when you don't know the exact name or want to filter by multiple criteria, use the Search Packages API instead.

📘

Note

The getPackage query returns a nullable StoredPackage type. When a projectKey is provided and the package does not exist in that project, the query returns null without an error. This allows aliased queries to return partial results when querying multiple packages across different projects. When projectKey is not provided and the package is not found, the query returns an error.

When operating in a self-managed environment, you must enable the OneModel service in the system.yaml file as a prerequisite to using this endpoint. Add the following:

metadata:
  onemodel:
    enabled: true

Since: 7.104.2

Security: Requires a valid token. Requires Read permissions to the repositories containing the package

Usage: POST /metadata/api/v1/onemodel/query

Sample query:

query {
  storedPackages {
    getPackage(name: "my-package", type: npm) {
      name
      type
      repositoryPackageType
      description
      latestVersionName
      versionsCount
      createdAt
      modifiedAt
      tags {
        name
      }
      qualifiers {
        name
        value
      }
    }
  }
}

Input Parameters

Output Types

The output types that you include in the query determine the data returned about the package.

StoredPackage Type

This type represents a single package record.

StoredPackageTag Type

This type represents a tag attached to a package.

StoredPackageQualifier Type

This type represents a key-value qualifier attached to a package.

StoredPackageStats Type

This type represents download statistics for a package.

StoredPackageLicense Type (Deprecated)

Warning: This type is deprecated. XRay data flow to Metadata will be removed. Use XRay APIs for license information.

StoredPackageVulnerabilitiesSummary Type (Deprecated)

Warning: This type is deprecated. XRay data flow to Metadata will be removed. Use XRay APIs for vulnerability information.

📘

Note

For details about fields that are common across all OneModel domains, see OneModel GraphQL Common Patterns and Conventions.

Return Behavior

The following table describes the return behavior.

Status Codes

The following table lists the status codes and their meanings.

Get Package - Examples

The following examples demonstrate how to use the Get Package API effectively:

• Example 1: Get basic package information
• Example 2: Get package with project key
• Example 3: Get package with version information
• Example 4: Get package with full nested data
• Example 5: Query multiple packages with project keys (aliased query)

Example 1: Get basic package information

This query fetches essential information about a package.

Query:

query GetBasicPackageInfo {
  storedPackages {
    getPackage(name: "lodash", type: npm) {
      name
      type
      description
      latestVersionName
      versionsCount
      createdAt
      modifiedAt
    }
  }
}

cURL Request:

curl -X POST -H "Authorization: Bearer <YOUR_TOKEN>" -H "Content-Type: application/json" \
https://<YOUR_JFROG_URL>/metadata/api/v1/onemodel/query \
--data '{
    "query": "query GetBasicPackageInfo { storedPackages { getPackage(name: \"lodash\", type: npm) { name type description latestVersionName versionsCount createdAt modifiedAt } } }"
}'

Sample Response:

{
  "data": {
    "storedPackages": {
      "getPackage": {
        "name": "lodash",
        "type": "npm",
        "description": "Lodash modular utilities.",
        "latestVersionName": "4.17.21",
        "versionsCount": 127,
        "createdAt": "2023-01-15T10:30:00.000Z",
        "modifiedAt": "2024-11-20T14:22:00.000Z"
      }
    }
  }
}

Example 2: Get package with project key

This query fetches a package scoped to a specific project. If the package doesn't exist in that project, it returns null without an error.

Query:

query GetPackageWithProjectKey {
  storedPackages {
    getPackage(name: "my-package", type: npm, projectKey: "my-project") {
      name
      type
      description
      latestVersionName
    }
  }
}

Sample Response (package exists in project):

{
  "data": {
    "storedPackages": {
      "getPackage": {
        "name": "my-package",
        "type": "npm",
        "description": "My package description",
        "latestVersionName": "1.0.0"
      }
    }
  }
}

Sample Response (package does not exist in project):

{
  "data": {
    "storedPackages": {
      "getPackage": null
    }
  }
}

Example 3: Get package with version information

This query fetches a package along with its first few versions.

Query:

query GetPackageWithVersions {
  storedPackages {
    getPackage(name: "spring-boot-starter", type: maven) {
      name
      type
      latestVersionName
      versionsConnection(first: 5, orderBy: {field: VERSION, direction: DESC}) {
        edges {
          node {
            version
            createdAt
            versionSize
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

Example 4: Get package with full nested data

This comprehensive query demonstrates how to request a package with all its related data including versions, locations, and artifacts.

Query:

query GetCompletePackageData {
  storedPackages {
    getPackage(name: "my-service", type: docker) {
      name
      type
      repositoryPackageType
      description
      latestVersionName
      tags {
        name
      }
      qualifiers {
        name
        value
      }
      stats {
        downloadCount
      }
      versionsConnection(first: 3) {
        edges {
          node {
            version
            createdAt
            versionSize
            tags {
              name
            }
            locationsConnection(first: 2) {
              edges {
                node {
                  repositoryKey
                  repositoryType
                  leadArtifactPath
                }
              }
            }
          }
        }
      }
    }
  }
}

Example 5: Query multiple packages with project keys (aliased query)

This example demonstrates how to query multiple packages across different projects using aliases. Packages that don't exist in their respective projects will return null without causing the entire query to fail.

Query:

query GetMultiplePackagesWithProjects {
  storedPackages {
    package1: getPackage(name: "lodash", type: npm, projectKey: "project-a") {
      name
      type
      latestVersionName
    }
    package2: getPackage(name: "react", type: npm, projectKey: "project-b") {
      name
      type
      latestVersionName
    }
    package3: getPackage(name: "angular", type: npm, projectKey: "project-a") {
      name
      type
      latestVersionName
    }
  }
}

Sample Response (when package2 doesn't exist in project-b):

{
  "data": {
    "storedPackages": {
      "package1": {
        "name": "lodash",
        "type": "npm",
        "latestVersionName": "4.17.21"
      },
      "package2": null,
      "package3": {
        "name": "angular",
        "type": "npm",
        "latestVersionName": "17.0.0"
      }
    }
  }
}

✅

Tip

When using aliased queries with projectKey, you can safely query multiple packages across different projects. Packages that don't exist in their specified projects will return null without affecting other results in the query.

Search Packages

Description: Returns the requested data from all package records that match the specified filters, as defined by the OneModel GraphQL query. Use this operation to search for packages using flexible filtering, ordering, and pagination.

Since: 7.104.2

Security: Requires a valid token. Requires Read permissions to the repositories containing the packages

Usage: POST /metadata/api/v1/onemodel/query

Sample query:

query {
  storedPackages {
    searchPackages(
      where: {
        nameHasPrefix: "spring"
        typeIn: ["maven"]
      }
      first: 20
      orderBy: {field: MODIFIED, direction: DESC}
    ) {
      edges {
        node {
          name
          type
          latestVersionName
          modifiedAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Input Types

StoredPackageWhereInput

This input type is used for filtering package objects. All filter elements are optional and can be combined using logical operators.

StoredPackageOrderInput

This input type specifies how to order the search results.

StoredPackageOrderField Enum

Possible values for ordering packages:

Pagination Parameters

Output Types

StoredPackageConnection Type

A connection type following the Relay Connection pattern for pagination.

StoredPackageEdge Type

An edge in a connection, containing a node and its cursor.

PageInfo Type

Page information as defined by the Relay PageInfo specification.

✅

Tip

The recommended approach is to limit the response data to those fields that are actually of interest. After returning the list of packages, you can use the Get Package API with nested queries to return detailed information about specific packages.

Status Codes

The following table lists the status codes and their meanings.

Search Packages - Examples

The following examples demonstrate how to use the Search Packages API effectively:

• Example 1: Search by package name prefix
• Example 2: Search by package type
• Example 3: Search with pagination
• Example 4: Search with multiple filters
• Example 5: Search packages with qualifiers
• Example 6: Search packages modified in date range

Example 1: Search by package name prefix

This query finds all packages whose names start with a specific prefix.

Query:

query SearchByNamePrefix {
  storedPackages {
    searchPackages(
      where: {nameHasPrefix: "spring-boot"}
      first: 10
      orderBy: {field: NAME, direction: ASC}
    ) {
      edges {
        node {
          name
          type
          latestVersionName
        }
      }
    }
  }
}

Sample Response:

{
  "data": {
    "storedPackages": {
      "searchPackages": {
        "edges": [
          {
            "node": {
              "name": "spring-boot-starter",
              "type": "maven",
              "latestVersionName": "3.2.0"
            }
          },
          {
            "node": {
              "name": "spring-boot-starter-web",
              "type": "maven",
              "latestVersionName": "3.2.0"
            }
          }
        ]
      }
    }
  }
}

Example 2: Search by package type

This query finds all packages of specific types.

Query:

query SearchByType {
  storedPackages {
    searchPackages(
      where: {
        typeIn: ["npm", "pypi"]
      }
      first: 20
    ) {
      edges {
        node {
          name
          type
          repositoryPackageType
          versionsCount
        }
      }
    }
  }
}

Example 3: Search with pagination

This example demonstrates how to paginate through large result sets.

Step 1: Request the first page and get the endCursor.

query SearchPackagesPage1 {
  storedPackages {
    searchPackages(
      where: {typeIn: ["docker"]}
      first: 10
    ) {
      edges {
        node {
          name
          latestVersionName
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Step 2: Use the endCursor to request the next page.

query SearchPackagesPage2 {
  storedPackages {
    searchPackages(
      where: {typeIn: ["docker"]}
      first: 10
      after: "CURSOR_FROM_PAGE_1"
    ) {
      edges {
        node {
          name
          latestVersionName
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Example 4: Search with multiple filters

This query combines multiple filter criteria to find specific packages.

Query:

query SearchWithMultipleFilters {
  storedPackages {
    searchPackages(
      where: {
        and: [
          {typeIn: ["maven", "gradle"]},
          {nameContains: "spring"},
          {modifiedAtGTE: "2024-01-01T00:00:00Z"}
        ]
      }
      first: 15
      orderBy: {field: MODIFIED, direction: DESC}
    ) {
      edges {
        node {
          name
          type
          modifiedAt
          latestVersionName
        }
      }
    }
  }
}

Example 5: Search packages with qualifiers

This query finds packages with specific qualifiers (key-value metadata).

Query:

query SearchWithQualifiers {
  storedPackages {
    searchPackages(
      where: {
        hasQualifiersWith: {
          or: [
            {name: "arch", value: "amd64"},
            {name: "os", value: "linux"}
          ]
        }
      }
      first: 20
    ) {
      edges {
        node {
          name
          type
          qualifiers {
            name
            value
          }
        }
      }
    }
  }
}

Example 6: Search packages modified in date range

This query finds packages modified within a specific time period.

Query:

query SearchByDateRange {
  storedPackages {
    searchPackages(
      where: {
        and: [
          {modifiedAtGTE: "2024-01-01T00:00:00Z"},
          {modifiedAtLTE: "2024-12-31T23:59:59Z"}
        ]
        typeIn: ["npm"]
      }
      first: 25
      orderBy: {field: MODIFIED, direction: DESC}
    ) {
      edges {
        node {
          name
          modifiedAt
          versionsCount
        }
      }
    }
  }
}

Search Package Versions

Description: Returns the requested data from all package version records that match the specified filters, as defined by the OneModel GraphQL query. Use this operation to search for package versions with flexible filtering, ordering, and pagination.

Since: 7.104.2

Security: Requires a valid token. Requires Read permissions to the repositories containing the package versions

Usage: POST /metadata/api/v1/onemodel/query

Sample query:

query {
  storedPackages {
    searchPackageVersions(
      where: {
        hasPackageWith: {
          name: "lodash"
          typeIn: ["npm"]
        }
        versionSizeGTE: 1000000
      }
      first: 20
      orderBy: {field: VERSION, direction: DESC}
    ) {
      edges {
        node {
          version
          versionSize
          createdAt
          package {
            name
            type
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Input Types

StoredPackageVersionWhereInput

This input type is used for filtering package version objects. All filter elements are optional and can be combined using logical operators.

StoredPackageVersionOrderInput

This input type specifies how to order the search results.

StoredPackageVersionOrderField Enum

Possible values for ordering package versions:

Output Types

StoredPackageVersionConnection Type

A connection type following the Relay Connection pattern for pagination.

StoredPackageVersionEdge Type

StoredPackageVersion Type

This type represents a single package version record.

StoredPackageVersionTag Type

StoredPackageVersionQualifier Type

StoredPackageVersionStats Type

StoredPackageVersionLocation Type

This type represents a location where a package version is stored.

StoredPackageVersionLocationStats Type

StoredPackageVersionLocationWhereInput

This input type is used for filtering package version location objects.

Status Codes

The following table lists the status codes and their meanings.

Search Package Versions - Examples

The following examples demonstrate how to use the Search Package Versions API effectively:

• Example 1: Search versions for a specific package
• Example 2: Filter by version size
• Example 3: Filter by creation date
• Example 4: Exclude pre-release versions
• Example 5: Search with locations and artifacts
• Example 6: Find versions with specific tags

Example 1: Search versions for a specific package

This query finds all versions of a specific package.

Query:

query SearchVersionsForPackage {
  storedPackages {
    searchPackageVersions(
      where: {
        hasPackageWith: {
          name: "react"
          typeIn: ["npm"]
        }
      }
      first: 20
      orderBy: {field: VERSION, direction: DESC}
    ) {
      edges {
        node {
          version
          createdAt
          versionSize
          package {
            name
            type
          }
        }
      }
    }
  }
}

Sample Response:

{
  "data": {
    "storedPackages": {
      "searchPackageVersions": {
        "edges": [
          {
            "node": {
              "version": "18.2.0",
              "createdAt": "2024-06-14T10:00:00.000Z",
              "versionSize": 2456789,
              "package": {
                "name": "react",
                "type": "npm"
              }
            }
          },
          {
            "node": {
              "version": "18.1.0",
              "createdAt": "2024-05-20T09:30:00.000Z",
              "versionSize": 2445123,
              "package": {
                "name": "react",
                "type": "npm"
              }
            }
          }
        ]
      }
    }
  }
}

Example 2: Filter by version size

This query finds large versions exceeding a certain size.

Query:

query FindLargeVersions {
  storedPackages {
    searchPackageVersions(
      where: {
        versionSizeGTE: 10000000
        hasPackageWith: {
          typeIn: ["docker"]
        }
      }
      first: 15
      orderBy: {field: VERSION, direction: DESC}
    ) {
      edges {
        node {
          version
          versionSize
          package {
            name
          }
        }
      }
    }
  }
}

Example 3: Filter by creation date

This query finds versions created within a specific time period.

Query:

query FindRecentVersions {
  storedPackages {
    searchPackageVersions(
      where: {
        and: [
          {createdAtGTE: "2024-01-01T00:00:00Z"},
          {createdAtLTE: "2024-12-31T23:59:59Z"}
        ]
        hasPackageWith: {
          nameHasPrefix: "spring"
        }
      }
      first: 25
      orderBy: {field: MODIFIED, direction: DESC}
    ) {
      edges {
        node {
          version
          createdAt
          package {
            name
            type
          }
        }
      }
    }
  }
}

Example 4: Exclude pre-release versions

This query finds only stable (non-pre-release) versions.

Query:

query FindStableVersions {
  storedPackages {
    searchPackageVersions(
      where: {
        ignorePreRelease: true
        hasPackageWith: {
          name: "angular"
          typeIn: ["npm"]
        }
      }
      first: 10
      orderBy: {field: VERSION, direction: DESC}
    ) {
      edges {
        node {
          version
          createdAt
        }
      }
    }
  }
}

Example 5: Search with locations and artifacts

This comprehensive query returns versions along with their storage locations and artifacts.

Query:

query SearchWithLocationsAndArtifacts {
  storedPackages {
    searchPackageVersions(
      where: {
        hasPackageWith: {
          name: "my-app"
          typeIn: ["docker"]
        }
      }
      first: 5
      orderBy: {field: VERSION, direction: DESC}
    ) {
      edges {
        node {
          version
          versionSize
          locationsConnection(first: 3) {
            edges {
              node {
                repositoryKey
                repositoryType
                leadArtifactPath
                stats {
                  downloadCount
                  lastDownloadedAt
                  remoteLastDownloadedAt
                }
              }
            }
          }
          artifactsConnection(first: 5) {
            edges {
              node {
                name
                sha256
                size
              }
            }
          }
        }
      }
    }
  }
}

Example 6: Find versions with specific tags

This query searches for versions that have specific tags.

Query:

query FindVersionsWithTags {
  storedPackages {
    searchPackageVersions(
      where: {
        hasTagsWith: {
          nameIn: ["latest", "stable", "production"]
        }
      }
      first: 20
    ) {
      edges {
        node {
          version
          tags {
            name
          }
          package {
            name
            type
          }
        }
      }
    }
  }
}

Search Package Artifacts

Description: Returns the requested data from all artifact records that match the specified filters, as defined by the OneModel GraphQL query. Use this operation to search for artifacts (files) by checksum, name, size, and other properties.

Since: 7.104.2

Security: Requires a valid token. Requires Read permissions to the repositories containing the artifacts

Usage: POST /metadata/api/v1/onemodel/query

Sample query:

query {
  storedPackages {
    searchPackageArtifacts(
      where: {
        sha256: "7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14"
      }
      first: 10
    ) {
      edges {
        node {
          name
          sha256
          size
          mimeType
          qualifiers {
            name
            value
          }
        }
      }
    }
  }
}

Input Types

StoredPackageArtifactWhereInput

This input type is used for filtering artifact objects. All filter elements are optional and can be combined using logical operators.

Output Types

StoredPackageArtifactConnection Type

A connection type following the Relay Connection pattern for pagination.

StoredPackageArtifactEdge Type

StoredPackageArtifact Type

This type represents a single artifact (file) record.

StoredPackageArtifactQualifier Type

Status Codes

The following table lists the status codes and their meanings.

Search Package Artifacts - Examples

The following examples demonstrate how to use the Search Package Artifacts API effectively:

• Example 1: Find artifact by SHA-256 checksum
• Example 2: Search artifacts by name pattern
• Example 3: Find large artifacts
• Example 4: Find artifacts with related package information
• Example 5: Search artifacts by MIME type

Example 1: Find artifact by SHA-256 checksum

This is the most reliable way to find a specific artifact.

Query:

query FindArtifactByChecksum {
  storedPackages {
    searchPackageArtifacts(
      where: {
        sha256: "7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14"
      }
      first: 1
    ) {
      edges {
        node {
          name
          sha256
          sha1
          md5
          size
          mimeType
        }
      }
    }
  }
}

cURL Request:

curl -X POST -H "Authorization: Bearer <YOUR_TOKEN>" -H "Content-Type: application/json" \
https://<YOUR_JFROG_URL>/metadata/api/v1/onemodel/query \
--data '{
    "query": "query FindArtifactByChecksum { storedPackages { searchPackageArtifacts(where: {sha256: \"7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14\"}, first: 1) { edges { node { name sha256 size mimeType } } } } }"
}'

Sample Response:

{
  "data": {
    "storedPackages": {
      "searchPackageArtifacts": {
        "edges": [
          {
            "node": {
              "name": "my-app-1.0.0.jar",
              "sha256": "7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14",
              "sha1": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
              "md5": "098f6bcd4621d373cade4e832627b4f6",
              "size": 15678234,
              "mimeType": "application/java-archive"
            }
          }
        ]
      }
    }
  }
}

Example 2: Search artifacts by name pattern

This query finds artifacts with names matching a pattern.

Query:

query SearchArtifactsByName {
  storedPackages {
    searchPackageArtifacts(
      where: {
        nameContains: ".jar"
        sizeGTE: 1000000
      }
      first: 20
    ) {
      edges {
        node {
          name
          size
          sha256
        }
      }
    }
  }
}

Example 3: Find large artifacts

This query finds artifacts exceeding a certain size.

Query:

query FindLargeArtifacts {
  storedPackages {
    searchPackageArtifacts(
      where: {
        sizeGTE: 50000000
      }
      first: 15
    ) {
      edges {
        node {
          name
          size
          mimeType
          sha256
        }
      }
    }
  }
}

Example 4: Find artifacts with related package information

This comprehensive query retrieves artifacts along with their parent package and version information.

Query:

query FindArtifactsWithPackageInfo {
  storedPackages {
    searchPackageArtifacts(
      where: {
        hasVersionsWith: {
          hasPackageWith: {
            nameHasPrefix: "spring"
            typeIn: ["maven"]
          }
        }
      }
      first: 10
    ) {
      edges {
        node {
          name
          sha256
          size
          mimeType
          qualifiers {
            name
            value
          }
        }
      }
    }
  }
}

Example 5: Search artifacts by MIME type

This query finds artifacts of specific types.

Query:

query SearchByMimeType {
  storedPackages {
    searchPackageArtifacts(
      where: {
        mimeTypeIn: [
          "application/java-archive",
          "application/x-executable",
          "application/octet-stream"
        ]
      }
      first: 25
    ) {
      edges {
        node {
          name
          mimeType
          size
          sha256
        }
      }
    }
  }
}

Common Patterns and Conventions

This section describes common patterns used across all Metadata GraphQL queries.

Pagination

The Metadata GraphQL API uses cursor-based pagination following the Relay Connection specification. This provides a consistent way to paginate through large result sets.

Key Concepts:

• Connection: A paginated collection of items (for example, StoredPackageConnection).
• Edge: A wrapper around each item that includes a cursor.
• Cursor: An opaque string that points to a specific position in the result set.
• PageInfo: Information about the current page and whether more pages exist.

Basic Pagination Pattern:

1. Request the first page with the first parameter:

   GraphQL

   {
     first: 10
   }

2. Check pageInfo.hasNextPage to see if more results exist.

3. Use pageInfo.endCursor with the after parameter to request the next page:

   GraphQL

   {
     first: 10
     after: "CURSOR_VALUE"
   }

Filtering

The Metadata API provides powerful filtering capabilities through WhereInput types.

Common Filter Operators:

• Equality: name: "value" (exact match)
• Negation: nameNEQ: "value" (not equal)
• List matching: nameIn: ["value1", "value2"] (matches any)
• String operations:
  • nameContains: "substring" (case-sensitive substring match)
  • nameHasPrefix: "prefix" (starts with)
• Numeric comparisons:
  • sizeGT: Greater than
  • sizeGTE: Greater than or equal
  • sizeLT: Less than
  • sizeLTE: Less than or equal
• Date comparisons:
  • createdAtGTE: On or after date
  • createdAtLTE: On or before date
• Boolean filters:
  • hasTags: true (has at least one tag)
  • hasTags: false (has no tags)
• Edge filters: Filter by properties of related entities
  • hasPackageWith: {...} (filter by package properties)
  • hasTagsWith: {...} (filter by tag properties)

Logical Operators:

• AND: Combine multiple conditions that must all be true

  GraphQL

  where: {
    and: [
      {typeIn: ["npm"]},
      {nameContains: "react"}
    ]
  }

• OR: Match any of the specified conditions

  GraphQL

  where: {
    or: [
      {name: "lodash"},
      {name: "underscore"}
    ]
  }

• NOT: Negate a condition

  GraphQL

  where: {
    not: {
      typeIn: ["maven"]
    }
  }

Ordering

Results can be ordered using the orderBy parameter:

orderBy: {
  field: MODIFIED
  direction: DESC
}

Available Directions:

• ASC: Ascending order (A-Z, 0-9, oldest-newest)
• DESC: Descending order (Z-A, 9-0, newest-oldest)

Date Format

Dates are returned in ISO 8601 format with millisecond precision and timezone:

2024-01-15T10:30:45.123Z

You can customize the date format using the @dateFormat directive:

createdAt @dateFormat(format: ISO8601_DATE_ONLY)

Available Formats:

• ISO8601: Full date and time (default) - 2024-01-15T10:30:45.123Z
• ISO8601_DATE_ONLY: Date only - 2024-01-15
• DD_MMM_YYYY: Human-readable - 15 Jan 2024

Nested Queries

The Metadata API supports deep nesting to return related data in a single request:

query {
  storedPackages {
    getPackage(name: "my-package", type: npm) {
      name
      versionsConnection(first: 5) {
        edges {
          node {
            version
            locationsConnection(first: 2) {
              edges {
                node {
                  repositoryKey
                  artifactsConnection(first: 3) {
                    edges {
                      node {
                        name
                        sha256
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

✅

Tip

When constructing nested queries, be mindful of performance. Deeply nested queries with large pagination limits can be resource-intensive. Request only the fields you need and use reasonable pagination limits (typically 10-50 items per connection).

Authentication and Authorization

Bearer Token Authentication

All Metadata GraphQL API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Example cURL request:

curl -X POST \
  -H "Authorization: Bearer eyJ2ZXIiOiIyIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYi..." \
  -H "Content-Type: application/json" \
  https://your-instance.jfrog.io/metadata/api/v1/onemodel/query \
  --data '{"query": "{ storedPackages { searchPackages(where: {typeIn: [\"npm\"]}, first: 10) { edges { node { name } } } } }"}'

Generating Access Tokens

Access tokens can be generated through:

1. JFrog Platform UI: User profile → Generate Token
2. JFrog CLI: jf access-token-create
3. Access API: REST API endpoint for token creation

Permission Requirements

The Metadata GraphQL API requires Read permissions to the repositories containing the packages, versions, or artifacts you want to query.

Permission Scoping:

• Queries automatically filter results based on the account's permissions
• Users can only see packages in repositories they have Read access to
• Project-scoped queries further restrict results to specific JFrog projects

Multi-Project Filtering:

When working in a multi-project JFrog instance, you can filter queries by project:

where: {
  projectKey: "my-project"
  nameHasPrefix: "my-package"
}

📘

Note

Tokens should be stored securely and rotated regularly. Never commit tokens to source control or expose them in client-side code.

GraphQL Schema Reference

Custom Scalar Types

The Metadata GraphQL API uses several custom scalar types:

Date

Date type following the ISO-8601 standard with millisecond precision and timezone.

Format: YYYY-MM-DDTHH:mm:ss.sssZ

Example: 2024-01-15T10:30:45.123Z

Cursor

An opaque string representing a position during pagination, as defined by the Relay Cursor specification.

Usage: Used with after parameter for pagination.

PackageType

A scalar type representing package types supported by JFrog Artifactory. Accepts string values for package types.

Common Values: npm, maven, docker, pypi, nuget, go, rpm, debian, gradle, ivy, sbt, composer, conan, cargo, helm, cocoapods, bower, chef, puppet, cran, conda, p2, swift, pub, huggingfaceml, huggingfacedataset, machinelearning, machinelearningdataset, oci, terraformmodule, terraformprovider, terraformbackend, vagrant, nix, opkg, dsc, alpine, ansible, bazelmodules, hex, jetbrainsplugins, jem, nimmodel, rubygems, gems, gav

Note: Some package types have aliases. For example, maven maps to gav in the database, and gems maps to rubygems. The API accepts the user-facing names (for example, maven, gems) and handles the conversion automatically.

Example: npm, maven, docker

Sha256

SHA-256 hash string formatted as lowercase hexadecimal.

Format: 64-character lowercase hex string

Example: 7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14

JSON

Arbitrary JSON object used for storing flexible data structures.

Common Directives

@owner

Indicates the JFrog product that owns a specific type or field.

type StoredPackage @owner(product: "jfmd") {
  # ...
}

@deprecated

Marks a field as deprecated with an optional reason.

licenses: [StoredPackageLicense!] @deprecated(reason: "XRay data flow to Metadata will be removed")

@validation

Specifies validation constraints for input fields.

first: Int! @validation(constraints: "gte=1,lte=50")

@dateFormat

Executable directive to specify the date format for Date fields in the query response.

createdAt @dateFormat(format: ISO8601_DATE_ONLY)

SortOrderDirection Enum

Possible directions for ordering results.

GraphiQL Playground

For interactive exploration of the Metadata GraphQL API, you can use the built-in GraphiQL interface:

URL: https://<YOUR_JFROG_URL>/metadata/api/v1/onemodel/graphiql

📘

Note

The GraphiQL interface requires authentication. You must be logged into the JFrog Platform or provide a valid access token.

Features:

• Auto-completion: Press Ctrl+Space for field and argument suggestions
• Documentation explorer: Click "Docs" to browse the complete schema
• Query history: Access previous queries
• Query validation: Real-time syntax checking

Best Practices

1. Request Only Required Fields

GraphQL allows you to request exactly the data you need. Avoid requesting unnecessary fields, especially large fields like predicate or deeply nested connections.

Good:

{
  name
  type
  latestVersionName
}

Avoid:

{
  name
  type
  # ... all possible fields including large nested data
}

2. Use Appropriate Pagination Limits

Set reasonable first parameter values (typically 10-50) to balance performance and usability.

3. Leverage Filtering

Filter results on the server side rather than fetching all data and filtering client-side:

where: {
  typeIn: ["npm", "maven"]
  modifiedAtGTE: "2024-01-01T00:00:00Z"
}

4. Handle Pagination Properly

Always check pageInfo.hasNextPage and use the endCursor to request additional pages when needed.

5. Use Specific Queries

When you know the exact package or version you need, use getPackage instead of searchPackages for better performance.

6. Cache Results

Consider caching frequently accessed data on the client side to reduce API calls.

7. Monitor Token Expiration

Implement token refresh logic to handle expired tokens gracefully.

Troubleshooting

Common Error Messages

"Bad Credentials" (401)

Cause: Invalid or expired access token

Solution: Generate a new access token and update your Authorization header

"Permission Denied" (403)

Cause: Insufficient permissions to access the requested repositories

Solution: Ensure your user account has Read permissions to the relevant repositories

"Bad Request" (400)

Cause: Invalid query syntax or parameters

Solution: Check your GraphQL query syntax and ensure all required parameters are provided

"Not Found" (404)

Cause: The requested package or resource does not exist

Solution: Verify the package name and type are correct

Query Debugging Tips

1. Use GraphiQL: Test queries interactively in the GraphiQL interface
2. Start Simple: Begin with basic queries and gradually add complexity
3. Check Validation: Ensure first parameter is between 1 and 50
4. Verify Filters: Confirm filter values match the expected data type
5. Review Permissions: Ensure you have access to the queried repositories

Additional Resources

• OneModel GraphQL Common Patterns and Conventions
• GraphQL Specification
• Relay Connection Specification