Harbor API

Harbor REST API v2

Base: /api/v2.0. Latest stable: Harbor v2.15.1 (May 2026). API spec: Swagger 2.0 at api/v2.0/swagger.yaml. Built-in Swagger UI: https://<harbor>/devcenter-api-2.0.

Authentication

Bearer Token Flow

# Get token for push/pull access to a repo
TOKEN=$(curl -s -u "username:password" \
  "https://harbor.example.com/service/token?service=harbor-registry&scope=repository:project/repo:pull,push" \
  | jq -r '.token')

# Use for registry operations
curl -H "Authorization: Bearer $TOKEN" https://harbor.example.com/v2/_catalog

Robot Account Notes

• Secret shown only once at creation — Harbor does not store it
• Username format: robot$<prefix><account_name>
• System-level (v2.2.0+) or project-level scope
• Permissions: granular RBAC (push, pull, create, read, delete, list, etc.)

Key Endpoints

Health & Status

Project Management

Repository Management

Artifact Management

Vulnerability Scanning

Robot Accounts

Replication

Garbage Collection

OIDC / LDAP

System & Admin

Examples

# Create a project
curl -X POST https://harbor.example.com/api/v2.0/projects \
  -u "admin:Harbor12345" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "myapp", "public": false, "storage_limit": -1}'

# Create a robot account (system-level)
curl -X POST https://harbor.example.com/api/v2.0/robots \
  -u "admin:Harbor12345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "description": "CI/CD deployment robot",
    "level": "system",
    "permissions": [{
      "kind": "project",
      "namespace": "myapp",
      "access": [
        {"resource": "repository", "action": "pull"},
        {"resource": "repository", "action": "push"}
      ]
    }]
  }'

# Trigger artifact scan
curl -X POST "https://harbor.example.com/api/v2.0/projects/myapp/repositories/nginx/artifacts/latest/scan" \
  -u "admin:Harbor12345"

# Create a replication rule
curl -X POST https://harbor.example.com/api/v2.0/replication/policies \
  -u "admin:Harbor12345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backup-to-dr",
    "description": "Replicate to DR site",
    "trigger": {"type": "event_based"},
    "dest_registry": {"id": 2},
    "filters": [{"type": "name", "value": "myapp/**"}],
    "deletion": true,
    "override": true
  }'

# Search across Harbor
curl -s "https://harbor.example.com/api/v2.0/search?q=nginx" \
  -u "admin:Harbor12345"

# Trigger garbage collection
curl -X POST https://harbor.example.com/api/v2.0/system/gc \
  -u "admin:Harbor12345" \
  -H "Content-Type: application/json" \
  -d '{"schedule": {"type": "Weekly", "weekday": 0, "offtime": 0}}'

Common Mistakes

• Robot secret not saved — Secret is only returned on creation. Store it immediately.
• API version path — Always use /api/v2.0/, not /api/ (v1.x legacy path).
• OIDC users can't use basic auth — Must use OIDC ID token as Bearer token.
• Robot tokens auto-expire — Set duration in days on creation (default: no expiry).
• Scan reports deleted on v2.2 upgrade — Schema migration clears old scan data. Re-scan after upgrade.
• Bearer token scope — Token is scoped to the scope param in the /service/token request. Use repository:*:pull for read-only, repository:*:pull,push for write.