API recipes
All recipes use these helpers:
export E=https://entrepot.example.comexport ENTREPOT_TOKEN=ent_… # an administrator's token for the admin recipesapi() { curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -H 'Content-Type: application/json' "$@"; }jq is used to pick fields out of responses. Every endpoint is documented in
the API reference.
System
Section titled “System”api $E/api/v1/system/info # version, base URL, formats and kinds, OIDC, GitLab instancesapi $E/api/v1/me # who am I, groups, matched GitLab policies, scopes, adminapi -X POST $E/api/v1/maintenance/gc # garbage-collect now → {"removed": n}api "$E/api/v1/audit-events?limit=20&action=repository." # audit log, newest firstBlob stores
Section titled “Blob stores”api $E/api/v1/blob-stores | jq '.[] | {name, type, usage}'api -X POST $E/api/v1/blob-stores -d '{"name":"s3","type":"s3","s3":{"bucket":"my-bucket","region":"eu-west-2","redirectDownloads":true}}'api -X DELETE $E/api/v1/blob-stores/s3 # 409 while repositories use itRepositories
Section titled “Repositories”# createapi -X POST $E/api/v1/repositories -d '{"name":"npm-proxy","format":"npm","kind":"proxy","blobStore":"default","proxy":{"remoteUrl":"https://registry.npmjs.org"}}'api -X POST $E/api/v1/repositories -d '{"name":"npm-internal","format":"npm","kind":"hosted","blobStore":"default"}'api -X POST $E/api/v1/repositories -d '{"name":"npm-group","format":"npm","kind":"group","blobStore":"default","group":{"members":["npm-internal","npm-proxy"]}}'
# list (optionally by format), read one, with stats and your permissionsapi "$E/api/v1/repositories?format=npm" | jq -r '.[].name'api $E/api/v1/repositories/npm-group | jq '{url, permissions, stats}'
# update: PUT replaces every mutable field, so edit the current definitionapi $E/api/v1/repositories/npm-proxy \ | jq '{name, format, kind, blobStore, description, online, anonymousRead, proxy, scan, cleanup} | .anonymousRead = true' \ | api -X PUT $E/api/v1/repositories/npm-proxy -d @-
# delete a repository and all of its contentapi -X DELETE $E/api/v1/repositories/npm-oldUpload, download and search
Section titled “Upload, download and search”# generic multipart upload into a hosted repositorycurl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -F file=@app.tar.gz -F path=releases/1.4.0/app.tar.gz \ $E/api/v1/repositories/files/uploadcurl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -F file=@mypkg-1.0.0.tgz -F tag=next \ $E/api/v1/repositories/npm-internal/upload # npm: dist-tag (default latest)curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -F file=@mypkg_1.0_amd64.deb \ -F distribution=stable -F component=main $E/api/v1/repositories/apt-internal/upload
# search components across repositoriesapi "$E/api/v1/search?q=lodash&format=npm&limit=20" | jq '.[] | {id, repository, name, version, scanState}'
# components of one repository, and one component with its assetsapi "$E/api/v1/repositories/npm-internal/components?q=widgets&limit=50&offset=0"api $E/api/v1/components/$COMPONENT_ID
# browse and list assetsapi "$E/api/v1/repositories/files/browse?path=releases/"api "$E/api/v1/repositories/files/assets?prefix=releases/&limit=100" # then ?after=<next>
# download an asset by ID; delete an asset or a whole componentcurl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -o app.tar.gz $E/api/v1/assets/$ASSET_ID/contentapi -X DELETE $E/api/v1/assets/$ASSET_IDapi -X DELETE $E/api/v1/components/$COMPONENT_IDUploads use plain curl -F rather than the api helper, so curl sets the
multipart Content-Type and boundary itself.
Tokens and service accounts
Section titled “Tokens and service accounts”# personal tokensapi -X POST $E/api/v1/tokens -d '{"name":"laptop","scopes":["read","write"],"expiresInDays":30}' | jq -r .secretapi $E/api/v1/tokens | jq '.[] | {id, name, hint, scopes, expiresAt, lastUsedAt}'api -X DELETE $E/api/v1/tokens/$TOKEN_ID
# service accountsapi -X POST $E/api/v1/service-accounts -d '{"name":"jenkins","description":"Jenkins controller"}'api -X POST $E/api/v1/service-accounts/jenkins/tokens -d '{"name":"ci","scopes":["read","write"],"expiresInDays":90}' | jq -r .secretapi $E/api/v1/service-accounts/jenkins/tokensapi -X DELETE $E/api/v1/service-accounts/jenkins/tokens/$TOKEN_ID
# users seen through OIDC, and service accountsapi $E/api/v1/users | jq '.[] | {username, groups, serviceAccount, lastLoginAt}'Roles and bindings
Section titled “Roles and bindings”api $E/api/v1/roles | jq '.[] | {name, actions, builtin}'api -X POST $E/api/v1/roles -d '{"name":"publisher","actions":["read","write"]}'
api -X POST $E/api/v1/role-bindings -d '{"role":"viewer","subjectType":"authenticated","repositoryPattern":"*"}'api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"group","subject":"developers","repositoryPattern":"*-internal"}'api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"user","subject":"sa:jenkins","repositoryPattern":"docker-internal"}'api $E/api/v1/role-bindings | jq '.[] | {id, role, subjectType, subject, repositoryPattern}'api -X DELETE $E/api/v1/role-bindings/$BINDING_IDGitLab trust policies
Section titled “GitLab trust policies”api -X POST $E/api/v1/gitlab-trust-policies -d '{ "name": "platform-releases", "gitlab": "gitlab", "conditions": {"project_path": "platform/**", "ref_protected": "true"}}'api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"gitlab_policy","subject":"platform-releases","repositoryPattern":"*-internal"}'api -X PUT $E/api/v1/gitlab-trust-policies/platform-releases -d '{ "name": "platform-releases", "gitlab": "gitlab", "conditions": {"project_path": "platform/**", "ref_protected": "true", "ref_type": "tag"}}'Signing keys
Section titled “Signing keys”api $E/api/v1/repositories/apt-internal/signing-key | jq -r .publicKey > apt-internal.ascapi -X POST $E/api/v1/repositories/apt-internal/signing-key/rotatejq -n --rawfile k key.asc '{privateKey: $k}' | api -X PUT $E/api/v1/repositories/apt-internal/signing-key -d @-Scanners, scans and waivers
Section titled “Scanners, scans and waivers”api -X POST $E/api/v1/scanners -d '{"name":"trivy","type":"trivy","rescanIntervalHours":24,"trivy":{"serverUrl":"http://entrepot-trivy:4954"}}'api -X POST $E/api/v1/scanners/trivy/test # {"ok": true, "message": "...", "version": "..."}
# scan a component now (needs write) and read the resultsapi -X POST $E/api/v1/components/$COMPONENT_ID/scan -d '{"scanners":["trivy"]}'api $E/api/v1/components/$COMPONENT_ID/scans | jq '{scanState, quarantined, quarantineReason, findings: [.results[].findings[] | {vulnId, severity, waived}]}'
# the queueapi "$E/api/v1/scan-jobs?status=failed&limit=50"
# waiversapi -X POST $E/api/v1/waivers -d '{"vulnId":"CVE-2021-23337","repositoryPattern":"npm-*","componentPattern":"lodash@4.17.*","reason":"not exploitable here","expiresAt":"2027-01-31T00:00:00Z"}'api $E/api/v1/waiversapi -X DELETE $E/api/v1/waivers/$WAIVER_IDCleanup
Section titled “Cleanup”api -X POST $E/api/v1/cleanup-policies -d '{"name":"prune-snapshots","format":"npm","criteria":{"prereleaseOnly":true,"publishedOlderThanDays":30,"keepLatest":5}}'
# preview a policy against one repositoryapi -X POST "$E/api/v1/cleanup-policies/prune-snapshots/preview?repository=npm-internal" \ | jq '{assets, bytes, components: [.components[] | "\(.name)@\(.version)"]}'
# run a repository's policies now — dry run firstapi -X POST "$E/api/v1/repositories/npm-internal/cleanup?dryRun=true"api -X POST "$E/api/v1/repositories/npm-internal/cleanup?dryRun=false&policy=prune-snapshots"Routing rules
Section titled “Routing rules”api -X POST $E/api/v1/routing-rules -d '{"name":"no-internal-names","mode":"block","matchers":["^@acme/","^acme-"]}'api -X POST $E/api/v1/routing-rules/no-internal-names/test -d '{"path":"@acme/widgets"}' # {"allowed":false,"matched":"^@acme/"}api -X POST $E/api/v1/routing-rules/no-internal-names/test -d '{"path":"lodash"}' # {"allowed":true}api $E/api/v1/routing-rules/no-internal-names | jq .repositories # proxies using itUsage metrics and activity
Section titled “Usage metrics and activity”api "$E/api/v1/metrics/overview?range=7d" | jq '{scope, totals, top: [.topRepositories[] | .repository]}'api "$E/api/v1/repositories/npm-proxy/metrics?range=24h" | jq .totalsapi "$E/api/v1/activity?repository=npm-internal&kind=upload&limit=20"curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -o activity.csv "$E/api/v1/activity?format=csv&from=2026-11-01T00:00:00Z"