API Reference

vcpkg-harbor exposes a REST API compatible with vcpkg’s HTTP binary cache protocol.

Base URL

http://localhost:15151

Authentication

If authentication is enabled, include the appropriate header:

Token auth: Authorization: Bearer <token>
Basic auth: Authorization: Basic <base64(user:pass)>

Cache API

Every cache endpoint is served in two shapes: the plain path shown below, and the same path prefixed with a build tag.

HEAD|GET|PUT|DELETE /{tag}/{name}/{version}/{sha}/{triplet}
HEAD|GET|PUT|DELETE /{name}/{version}/{sha}/{triplet}

The tagged shape addresses one build stream’s isolated view of the cache, the untagged shape addresses the default namespace. A tag that is malformed or not allowlisted returns 400 Bad Request; if build tags are disabled the tagged shape returns 404 Not Found. See Build Tags.

Check Package Exists

Check if a package exists in the cache.

HEAD /{name}/{version}/{sha}

Parameters:

Name	Type	Description
name	string	Package name
version	string	Package version
sha	string	Package SHA hash

Responses:

Status	Description
200	Package exists
404	Package not found

Example:

curl -I http://localhost:15151/zlib/1.2.13/abc123def456

Download Package

Download a package from the cache.

GET /{name}/{version}/{sha}

Parameters:

Name	Type	Description
name	string	Package name
version	string	Package version
sha	string	Package SHA hash

Responses:

Status	Description
200	Binary package data (streaming)
404	Package not found

Example:

curl -o package.zip http://localhost:15151/zlib/1.2.13/abc123def456

Upload Package

Upload a package to the cache.

PUT /{name}/{version}/{sha}

Parameters:

Name	Type	Description
name	string	Package name
version	string	Package version
sha	string	Package SHA hash

Request Body: Binary package data

Responses:

Status	Description
200	Upload successful
409	Package already exists
403	Server is read-only
500	Upload failed

Example:

curl -X PUT --data-binary @package.zip \
  http://localhost:15151/zlib/1.2.13/abc123def456

Response:

{
  "status": "success",
  "name": "zlib",
  "version": "1.2.13",
  "sha": "abc123def456",
  "size": 1234567,
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "tag": null,
  "namespace": "_default",
  "deduplicated": false,
  "evicted": 0
}

Field	Description
tag	The build tag from the request path, `null` when untagged
namespace	The namespace the package was stored in
deduplicated	`true` when the bytes were already stored and only a reference was added
evicted	Number of packages the tag’s retention limits evicted

Delete Package

Delete a package from the cache.

DELETE /{name}/{version}/{sha}

Responses:

Status	Description
200	Package removed from the addressed namespace
404	The namespace does not hold the package
403	Server is read-only

With build tags, a delete only drops the addressed namespace’s reference. The stored bytes are removed once the last reference is gone.

Health API

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2024-01-15T10:30:00Z"
}

Liveness Check

GET /health/live

Response:

{
  "status": "alive",
  "timestamp": "2024-01-15T10:30:00Z"
}

Readiness Check

GET /health/ready

Responses:

Status	Description
200	Ready
503	Not ready

Detailed Health

GET /health/details

Response:

{
  "status": "healthy",
  "version": "2.0.0",
  "uptime": "1d 2h 30m",
  "storage": {
    "healthy": true,
    "backend": "minio",
    "total_packages": 1234,
    "total_size_bytes": 5678901234
  },
  "cache": {
    "hits": 5000,
    "misses": 500,
    "hit_rate": "90.9%"
  }
}

Metrics API

Prometheus Metrics

GET /metrics

Returns metrics in Prometheus text format.

OpenAPI Documentation

Interactive API documentation is available at:

Swagger UI: http://localhost:15151/api/docs
ReDoc: http://localhost:15151/api/redoc
OpenAPI JSON: http://localhost:15151/api/openapi.json