Skip to content

API recipes

All recipes use these helpers:

Terminal window
export E=https://entrepot.example.com
export ENTREPOT_TOKEN=ent_… # an administrator's token for the admin recipes
api() { 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.

Terminal window
api $E/api/v1/system/info # version, base URL, formats and kinds, OIDC, GitLab instances
api $E/api/v1/me # who am I, groups, matched GitLab policies, scopes, admin
api -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 first
Terminal window
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 it
Terminal window
# create
api -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 permissions
api "$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 definition
api $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 content
api -X DELETE $E/api/v1/repositories/npm-old
Terminal window
# generic multipart upload into a hosted repository
curl -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/upload
curl -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 repositories
api "$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 assets
api "$E/api/v1/repositories/npm-internal/components?q=widgets&limit=50&offset=0"
api $E/api/v1/components/$COMPONENT_ID
# browse and list assets
api "$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 component
curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -o app.tar.gz $E/api/v1/assets/$ASSET_ID/content
api -X DELETE $E/api/v1/assets/$ASSET_ID
api -X DELETE $E/api/v1/components/$COMPONENT_ID

Uploads use plain curl -F rather than the api helper, so curl sets the multipart Content-Type and boundary itself.

Terminal window
# personal tokens
api -X POST $E/api/v1/tokens -d '{"name":"laptop","scopes":["read","write"],"expiresInDays":30}' | jq -r .secret
api $E/api/v1/tokens | jq '.[] | {id, name, hint, scopes, expiresAt, lastUsedAt}'
api -X DELETE $E/api/v1/tokens/$TOKEN_ID
# service accounts
api -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 .secret
api $E/api/v1/service-accounts/jenkins/tokens
api -X DELETE $E/api/v1/service-accounts/jenkins/tokens/$TOKEN_ID
# users seen through OIDC, and service accounts
api $E/api/v1/users | jq '.[] | {username, groups, serviceAccount, lastLoginAt}'
Terminal window
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_ID
Terminal window
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"}
}'
Terminal window
api $E/api/v1/repositories/apt-internal/signing-key | jq -r .publicKey > apt-internal.asc
api -X POST $E/api/v1/repositories/apt-internal/signing-key/rotate
jq -n --rawfile k key.asc '{privateKey: $k}' | api -X PUT $E/api/v1/repositories/apt-internal/signing-key -d @-
Terminal window
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 results
api -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 queue
api "$E/api/v1/scan-jobs?status=failed&limit=50"
# waivers
api -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/waivers
api -X DELETE $E/api/v1/waivers/$WAIVER_ID
Terminal window
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 repository
api -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 first
api -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"
Terminal window
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 it
Terminal window
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 .totals
api "$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"