Stored Packages OneModel GraphQL

You can use the Stored Packages OneModel GraphQL API to query JFrog Artifactory metadata, list package records, filter package versions, and locate artifacts by checksum and properties. This API follows the OneModel GraphQL conventions and supports pagination, filtering, and federated queries alongside other OneModel domains.

Prerequisites

• Requires JFrog Artifactory version 7.104.2 or later.

• In a self-managed environment, add the following to the system.yaml file to enable Metadata OneModel.

  YAML

  metadata:
    onemodel:
      enabled: true

• Token audience should be wildcard (*@*) for the unified OneModel gateway, or jfmd@*.

• Read access to every repository that contains the packages, versions, or artifacts you query. Results are filtered to match your read access, including project scope where applicable.

Subgraph Summary

This subgraph exposes the Metadata domain for software stored in JFrog Artifactory. It is exposed under the storedPackages namespace and is designed around Relay-style connections for pagination. It supports filtering, ordering, edge filters across related entities, and federated usage with other OneModel domains.

Queries in the examples below use the unified OneModel gateway at POST <your-jfrog-domain>/onemodel/api/v1/graphql.

Query Entry Points

Query.storedPackages is the root for package, version, and artifact queries.

The following table lists query operations and their descriptions.

Main Entities

Stored Packages Domain

• StoredPackage: a single package record identified by name and PackageType; includes summary fields (description, latestVersionName, versionsCount, timestamps) and links to versions, tags, and qualifiers.
• StoredPackageVersion: a single release of a package (version string, size, timestamps); references its parent package and exposes locations and artifacts.
• StoredPackageVersionLocation: where a version is stored in Artifactory (repositoryKey, repositoryType, leadArtifactPath); references the parent version and exposes artifacts at that location via artifactsConnection.
• StoredPackageArtifact: a stored file (name, checksums, size, mimeType). Reach artifacts via artifactsConnection on a version or location; filter artifact searches by parent criteria using hasVersionsWith and hasVersionsLocationsWith.
• StoredPackageTag / StoredPackageVersionTag: tags attached to packages or versions; filterable via hasTags / hasTagsWith.
• StoredPackageQualifier / StoredPackageVersionQualifier / StoredPackageArtifactQualifier: key-value metadata on packages, versions, or artifacts.
• StoredPackageStats / StoredPackageVersionStats / StoredPackageVersionLocationStats: download statistics at package, version, or location level.
• StoredPackageConnection / StoredPackageVersionConnection / StoredPackageArtifactConnection (and corresponding Edge types): paginated wrappers used when returning lists.

Shared Conventions

• PageInfo and Cursor: standard Relay cursor pagination primitives (first, after, pageInfo.hasNextPage, pageInfo.endCursor).
• Common scalars include Date, PackageType, and Sha256.
• WhereInput types on each search operation support equality, ranges, string matching, logical and / or / not, and edge filters (for example, hasPackageWith, hasVersionsWith) to filter by related entities.

Entity Relationships

• StoredPackage -> StoredPackageVersion (one-to-many): a package has many versions via versionsConnection.
• StoredPackageVersion -> StoredPackage (many-to-one): each version references its parent package.
• StoredPackageVersion -> StoredPackageVersionLocation (one-to-many): a version's storage locations via locationsConnection (repositoryKey, repositoryType, leadArtifactPath).
• StoredPackageVersion -> StoredPackageArtifact (one-to-many): a version includes many files via artifactsConnection.
• StoredPackageVersionLocation -> StoredPackageVersion (many-to-one): each location references its parent version.
• StoredPackageVersionLocation -> StoredPackageArtifact (one-to-many): artifacts at a specific repository path via artifactsConnection.

StoredPackage
  └── StoredPackageVersion
        ├── StoredPackageVersionLocation ──► StoredPackageArtifact
        └── StoredPackageArtifact

Traversal Patterns

• Package-centric: getPackage or searchPackages, then traverse versionsConnection → locationsConnection and/or artifactsConnection. Prefer getPackage when name and type (or repositoryPackageType) are known.
• Location-centric: getPackageVersionLocation when you know package name, version, and repository key.
• Version-centric: searchPackageVersions with hasPackageWith (or other version filters), then read package, locationsConnection, or artifactsConnection.
• Artifact-centric: searchPackageArtifacts (for example, by sha256), and use edge filters such as hasVersionsWith and hasVersionsLocationsWith to narrow results by parent version, package, or location criteria. To read parent metadata, use package- or version-centric queries (for example, package on StoredPackageVersion).
• Connections return edges { node } and pageInfo for uniform pagination across search operations.

Notes

• Results are scoped to repositories you have Read permission on; search operations return empty connections when nothing is readable. On getPackage, a missing package or no read access returns null with a GraphQL error in the response. Invalid or missing authentication returns HTTP 403. Project membership failures return GraphQL errors in the response body (typically HTTP 200).
• On getPackage, provide at least one of type or repositoryPackageType along with name. Optional projectKey scopes the lookup to a JFrog project: when set and the package is not in that project, the query returns null without failing aliased multi-package queries. Without projectKey, a missing package or no read access returns null with a GraphQL error.
• licenses and vulnerabilitiesSummary on package and version types are deprecated. Xray data flow into Metadata is being removed—use Xray APIs for license and vulnerability data.
• For pagination, filtering, and ordering conventions shared across OneModel domains, see JFrog OneModel GraphQL.

Common Use Cases

Get Package by Name and Type

Use this when you already know the package name and package type (for example, after you resolve it from a build) and want one record: latest version, tags, counts, and optional nested versionsConnection. Prefer getPackage over searchPackages for performance when the identifier is exact.

GraphQL

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

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { storedPackages { getPackage(name: \"my-package\", type: \"npm\") { name type repositoryPackageType description latestVersionName versionsCount createdAt modifiedAt tags { name } qualifiers { name value } } } }"}'

Search Packages With Filters and Pagination

Use this to explore inventory when names are partial or you need filters (type, dates, tags, and project). Request first with a value from one to 50, plus orderBy and pageInfo, for cursor-based pagination per the Relay connection pattern.

GraphQL

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

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"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 } } } }"}'

Search Package Versions for a Package

Use this to audit or select versions: filter by parent package (hasPackageWith), size, dates, pre-release flags, and tags. Add nested locationsConnection or artifactsConnection when you need physical layout.

GraphQL

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

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { storedPackages { searchPackageVersions(where: { hasPackageWith: { name: \"lodash\", typeIn: [\"npm\"] } }, first: 20, orderBy: { field: VERSION, direction: DESC }) { edges { node { version versionSize createdAt package { name type } } } pageInfo { hasNextPage endCursor } } } }"}'

Search Package Artifacts by Checksum or Attributes

Use this to resolve a binary to metadata: SHA-256 is the most reliable key. You can combine name patterns, MIME type, size, and edge filters to related versions.

GraphQL

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

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { storedPackages { searchPackageArtifacts(where: { sha256: \"7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14\" }, first: 10) { edges { node { name sha256 size mimeType qualifiers { name value } } } } } }"}'