Relic API
The Relic API's schema is the protobuf files in api/proto/relic/v1. Every
method is served under /api/ in each protocol, with the same access checks.
Generated clients are in SDK.
| Protocol | Request |
|---|---|
| REST | resource URLs under /api/v1/, such as GET /api/v1/repositories/libs-local. The API reference lists every route. |
| Connect | POST /api/relic.v1.<Service>/<Method> with a JSON or binary protobuf body. The web UI and the relic CLI use it. |
| gRPC-Web | the Connect paths |
| gRPC | the Connect paths. Needs HTTP/2, which the server offers only when it serves HTTPS itself (not with --no-tls). |
In JSON, field names are lowerCamelCase (deploy_to is deployTo), enums are
their names (?class=REPOSITORY_CLASS_LOCAL in REST query strings too), and
64-bit integers are strings. An item path in a REST URL (the {path} of
/api/v1/repositories/{repository}/items/{path}) keeps its slashes or sends
them percent-encoded as %2F; both find the item.
Authentication and access
Send Basic credentials (-u user:password-or-token) or an
Authorization: Bearer <token> header. The web UI's session cookie works under
/api/ only, and writes made with it need the X-Relic-UI: 1 header.
Every method declares an access level in the proto (option (relic.v1.access)):
PUBLIC, AUTHENTICATED (any signed-in user; items are still checked against
permissions), VIEWER (viewers and administrators) or ADMIN.
Errors use Connect's codes. Over REST, each maps to an HTTP status:
| Code | HTTP status |
|---|---|
invalid_argument, failed_precondition, out_of_range | 400 |
unauthenticated | 401 |
permission_denied | 403 |
not_found (also for what the caller may not read) | 404 |
already_exists, aborted | 409 |
resource_exhausted | 429 |
unimplemented | 501 |
unavailable | 503 |
deadline_exceeded | 504 |
internal, data_loss, unknown | 500 |
Error bodies are {"code": "...", "message": "..."} over Connect, with a
numeric code over REST. The file routes answer like REST,
with three more statuses: 405 for a method a route does not serve, 413 for
an upload over the size limit or the repository's quota, and 507 when storage
is full.
Services
| Service | Signed-in users | Viewers and administrators | Administrators |
|---|---|---|---|
SystemService | GetVersion (public), GetDashboardSummary | GetSystemStatus, ListBackgroundJobs, GetUsageReport | CheckStorage, CollectGarbage |
SessionService | Login, Logout, ListSignInProviders, GetSignInNote, ExchangeWorkloadToken, StartWebLogin and PollWebLogin, all public; GetCurrentUser, ApproveLogin | ||
RepositoryService | ListRepositories, GetRepository, GetClientEndpoints, GetRepositorySigningKey, CreateRepository*, UpdateRepository*, DeleteRepository* | ||
ArtifactService | StatItem, ListChildren, SearchItems, GetItemDetails, Get/Set/DeleteProperties, CopyItem, MoveItem, DeleteItem, ListArchiveEntries | GetEffectivePermissions | |
PackageService | GetContainerImage, PromoteContainerImage, GetNpmPackage, GetPythonPackage, GetHelmChart | ||
BuildService | ListBuilds, PublishBuildRun, ListBuildRuns, GetBuildRun, DeleteBuildRuns, ApplyBuildRetention, PromoteBuildRun | ||
ReleaseService | ListReleases, ListReleaseVersions, GetRelease, Create/Update/Finalize/DeleteRelease, SetReleaseTag, PromoteRelease, List/DeleteReleasePromotion(s), ExportRelease | ||
EvidenceService | ListEvidence, CreateEvidence | ListTrustedKeys | AddTrustedKey, DeleteTrustedKey |
SigningKeyService | GetPublicKey | ListKeyPairs | DeleteKeyPair |
SecurityService | CreateToken, ListTokens, RevokeToken | ListUsers, GetUser, ListGroups, GetGroup, ListPermissions, GetPermission | Put/DeleteUser, Put/DeleteGroup, Put/DeletePermission |
ProjectService | ListProjects, GetProject, SetProjectMembers*, AddProjectMember*, RemoveProjectMember* | PutProject, DeleteProject | |
WorkloadIdentityService | ListWorkloadIdentities, GetWorkloadIdentity | Put/DeleteWorkloadIdentity | |
IdentityProviderService | ListIdentityProviders, GetIdentityProvider | Put/DeleteIdentityProvider | |
LdapService | ListLdapServers, ListLdapGroupMappings | Put/DeleteLdapServer, Put/DeleteLdapGroupMapping, TestLdapSignIn | |
ScanService | GetItemScan, GetItemSbom, ExplainDownload, CheckPackage, ScanBuildRun, GetBuildRunScan, ScanPackages, GetPackagesScan | ListFindings, ListOperationalRisks, GetEndOfLifeStatus, ListCves, GetCve, ListPolicies, ListWatches, ListIgnoreRules, ExportVex | Put/DeletePolicy, Put/DeleteWatch, Create/DeleteIgnoreRule, ImportVex |
PolicyDecisionService | ListPolicyDecisions | PreviewPolicy | |
QuarantineService | ListQuarantined | ReleaseQuarantined, RejectQuarantined | |
WaiverService | RequestWaiver, ListWaivers, WithdrawWaiver | ApproveWaiver, RejectWaiver | |
PromotionGateService | ListPromotionGates, GetPromotionGate | Put/DeletePromotionGate | |
CleanupService | ListCleanupPolicies, GetCleanupPolicy, PreviewCleanupPolicy | Put/DeleteCleanupPolicy, RunCleanupPolicy | |
HoldService | ListHolds | PutHold, DeleteHold | |
ReplicationService | ListReplications, GetReplication | Put/DeleteReplication, RunReplication | |
TrashService | ListTrash | RestoreTrash, DeleteTrashEntry, EmptyTrash | |
AuditService | ListAuditEvents | ||
WebhookService | ListWebhooks, GetWebhook, ListWebhookDeliveries | Put/DeleteWebhook, PingWebhook | |
AgentRegistryService | ListRegistryEntries | ApproveRegistryEntry, RevokeRegistryApproval |
* administrators, and the project's admins: for a repository, the admins of the project it belongs to.
- Builds, releases and evidence check the caller's build, release and item permissions on each call.
ListTokensandRevokeTokencover the caller's own tokens. Administrators cover everyone's; viewers list everyone's.- Members see their projects in
ListProjectsandGetProject, and their own waivers inListWaivers; administrators and viewers see all.ListRegistryEntriesshows unapproved entries to administrators and viewers only. Put…methods create or replace.- Secrets (passwords, webhook and client secrets) are write-only; an update without one keeps the stored value. A stored password stays only while the URL it is sent to keeps its scheme, host and port; URLs cannot hold a user or password.
File contents
Messages never carry file bytes. File contents use plain HTTP with the same credentials and permissions:
| Request | Does |
|---|---|
GET/HEAD /api/v1/files/<repo>/<path> | download (ranges supported) |
PUT /api/v1/files/<repo>/<path> | upload; query parameters set properties (?build.name=app), which needs annotate permission. Overwriting needs delete permission. |
GET /api/v1/archive/<repo>/<path>?entry=<entry> | one entry of a zip or tar file |
GET /api/v1/sbom/<repo>/<path>?format=cyclonedx|spdx|syft | the item's SBOM as CycloneDX 1.6 (default), SPDX 2.3 or Syft JSON |
PUT /api/v1/sbom/<repo>/<path> | replace the item's SBOM (write permission on every file with the item's content) |
POST /api/v1/releases/import | import a release archive (administrators) |
PUT /api/v1/vulnerability-database | import a vulnerability database archive (administrators) |
PUT /api/v1/end-of-life-data | import endoflife.date's product data (administrators) |
Examples
Create a local Maven repository (administrators):
curl -s -u <user>:<token> -H 'Content-Type: application/json' \
https://relic.example.com/api/v1/repositories \
-d '{"name":"libs-local","class":"REPOSITORY_CLASS_LOCAL","format":"FORMAT_MAVEN"}'
Get the repository over Connect:
curl -s -u <user>:<token> -H 'Content-Type: application/json' -d '{"name":"libs-local"}' \
https://relic.example.com/api/relic.v1.RepositoryService/GetRepository
Upload a file:
curl -s -u <user>:<token> -T app-1.0.jar https://relic.example.com/api/v1/files/libs-local/org/app/1.0/app-1.0.jar