Skip to content
Artifact Keeper

REST API Reference

Artifact Keeper provides a comprehensive REST API for managing artifacts, repositories, users, and system configuration.

Base URL

https://registry.example.com/api/v1

Authentication

Most endpoints require authentication via JWT token:

Authorization: Bearer <access_token>

Demo Mode

Important: All write endpoints (POST, PUT, DELETE) return 403 Forbidden in demo mode. Only GET requests are allowed.

Authentication Endpoints

POST /auth/login

Authenticate and receive access/refresh tokens.

Request:

{
  "username": "admin",
  "password": "admin"
}

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 900,
  "token_type": "Bearer"
}

POST /auth/refresh

Refresh access token using refresh token.

Request:

{
  "refresh_token": "eyJhbGc..."
}

Response:

{
  "access_token": "eyJhbGc...",
  "expires_in": 900
}

POST /auth/logout

Invalidate current session.

Headers: Authorization: Bearer <token>

Response: 204 No Content

Repository Endpoints

GET /repositories

List all repositories.

Query Parameters:

  • page (number): Page number (default: 1)
  • limit (number): Items per page (default: 20)
  • format (string): Filter by format (docker, maven, npm, etc.)

Response:

{
  "repositories": [
    {
      "id": "repo-123",
      "name": "my-docker-repo",
      "format": "docker",
      "description": "Production Docker images",
      "created_at": "2026-01-15T10:00:00Z",
      "artifact_count": 142,
      "size_bytes": 5368709120
    }
  ],
  "total": 10,
  "page": 1,
  "limit": 20
}

POST /repositories

Create a new repository.

Request:

{
  "name": "my-maven-repo",
  "format": "maven",
  "description": "Maven artifacts",
  "public": false
}

Response: 201 Created

GET /repositories/:id

Get repository details.

Response:

{
  "id": "repo-123",
  "name": "my-docker-repo",
  "format": "docker",
  "description": "Production Docker images",
  "public": false,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-01T12:00:00Z",
  "artifact_count": 142,
  "size_bytes": 5368709120
}

PUT /repositories/:id

Update repository settings.

Request:

{
  "description": "Updated description",
  "public": true
}

Response: 200 OK

DELETE /repositories/:id

Delete repository and all artifacts.

Response: 204 No Content

Artifact Endpoints

GET /artifacts/:id

Get artifact metadata.

Response:

{
  "id": "artifact-456",
  "repository_id": "repo-123",
  "package_name": "my-app",
  "version": "1.2.3",
  "format": "docker",
  "size_bytes": 104857600,
  "checksums": {
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "uploaded_at": "2026-02-01T12:00:00Z",
  "uploaded_by": "alice"
}

GET /artifacts/:id/download

Download artifact file.

Response: Binary file with appropriate Content-Type header.

Package Endpoints

GET /packages

Search and list packages.

Query Parameters:

  • query (string): Search query
  • repository_id (string): Filter by repository
  • format (string): Filter by format
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "packages": [
    {
      "name": "my-app",
      "repository_id": "repo-123",
      "format": "docker",
      "latest_version": "1.2.3",
      "version_count": 15,
      "total_size_bytes": 1572864000,
      "last_updated": "2026-02-01T12:00:00Z"
    }
  ],
  "total": 50
}

GET /packages/:name/versions

List all versions of a package.

Response:

{
  "versions": [
    {
      "version": "1.2.3",
      "artifact_id": "artifact-456",
      "size_bytes": 104857600,
      "uploaded_at": "2026-02-01T12:00:00Z"
    }
  ]
}

User Endpoints

GET /users

List users (admin only).

Response:

{
  "users": [
    {
      "id": "user-789",
      "username": "alice",
      "email": "alice@example.com",
      "role": "user",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

POST /users

Create user (admin only).

Request:

{
  "username": "bob",
  "email": "bob@example.com",
  "password": "secure-password",
  "role": "user"
}

Response: 201 Created

GET /users/me

Get current user profile.

PUT /users/me

Update current user profile.

DELETE /users/:id

Delete user (admin only).

Group Endpoints

GET /groups

List groups.

POST /groups

Create group (admin only).

Request:

{
  "name": "developers",
  "description": "Development team"
}

POST /groups/:id/members

Add users to group.

Request:

{
  "user_ids": ["user-789", "user-890"]
}

Permission Endpoints

GET /permissions

List permissions.

POST /permissions

Grant permissions.

Request:

{
  "repository_id": "repo-123",
  "user_id": "user-789",
  "permissions": ["read", "write"]
}

DELETE /permissions/:id

Revoke permissions.

Security Endpoints

GET /security/scans

List security scans.

Response:

{
  "scans": [
    {
      "id": "scan-123",
      "artifact_id": "artifact-456",
      "scanner": "trivy",
      "status": "completed",
      "vulnerabilities": {
        "critical": 0,
        "high": 2,
        "medium": 5,
        "low": 12
      },
      "scanned_at": "2026-02-01T12:30:00Z"
    }
  ]
}

POST /security/scans

Trigger security scan.

Request:

{
  "artifact_id": "artifact-456",
  "scanner": "trivy"
}

GET /security/scans/:id

Get scan details and report.

GET /security/policies

List security policies.

POST /security/policies

Create security policy (admin only).

Plugin Endpoints

GET /plugins

List installed plugins.

Response:

{
  "plugins": [
    {
      "id": "plugin-123",
      "name": "format-handler-conan",
      "version": "1.0.0",
      "enabled": true,
      "capabilities": ["format_handler"]
    }
  ]
}

POST /plugins

Install plugin (admin only).

POST /plugins/:id/enable

Enable plugin.

POST /plugins/:id/disable

Disable plugin.

DELETE /plugins/:id

Uninstall plugin.

Webhook Endpoints

GET /webhooks

List webhooks.

POST /webhooks

Create webhook.

Request:

{
  "url": "https://example.com/webhook",
  "events": ["artifact.uploaded", "scan.completed"],
  "secret": "webhook-secret"
}

PUT /webhooks/:id

Update webhook.

DELETE /webhooks/:id

Delete webhook.

POST /webhooks/:id/test

Send test webhook.

Admin Endpoints

GET /admin/backups

List backups (admin only).

POST /admin/backups

Create backup (admin only).

Request:

{
  "description": "Manual backup",
  "include_artifacts": true
}

POST /admin/backups/:id/restore

Restore from backup (admin only).

GET /admin/settings

Get system settings (admin only).

PUT /admin/settings

Update system settings (admin only).

GET /admin/stats

Get system statistics (admin only).

Response:

{
  "repositories": 25,
  "artifacts": 1523,
  "total_size_bytes": 107374182400,
  "users": 42,
  "downloads_24h": 856
}

POST /admin/cleanup

Run garbage collection (admin only).

POST /admin/reindex

Reindex search database (admin only).

Search Endpoints

GET /search/quick

Quick search across artifacts.

Query Parameters:

  • q (string): Search query
  • limit (number): Max results (default: 10)

Response:

{
  "results": [
    {
      "type": "artifact",
      "name": "my-app",
      "version": "1.2.3",
      "repository": "my-docker-repo",
      "score": 0.95
    }
  ]
}

GET /search/advanced

Advanced search with filters.

Query Parameters:

  • query (string): Search query
  • format (string): Filter by format
  • repository (string): Filter by repository
  • min_date (ISO date): Uploaded after
  • max_date (ISO date): Uploaded before

GET /search/checksum

Search by checksum.

Query Parameters:

  • checksum (string): MD5, SHA1, or SHA256 hash

GET /search/suggest

Get search suggestions.

Query Parameters:

  • q (string): Partial query

Edge Node Endpoints

GET /edge-nodes

List edge nodes (admin only).

POST /edge-nodes

Register edge node (admin only).

DELETE /edge-nodes/:id

Deregister edge node (admin only).

POST /edge-nodes/:id/repositories

Assign repository to edge.

Migration Endpoints

GET /migrations

List migration jobs.

POST /migrations

Create migration from Artifactory.

Request:

{
  "source_url": "https://artifactory.example.com",
  "source_username": "admin",
  "source_password": "password",
  "repositories": ["libs-release", "libs-snapshot"]
}

GET /migrations/:id

Get migration status.

Signing Endpoints

GET /signing/keys

List signing keys.

POST /signing/keys

Generate signing key pair.

POST /signing/sign

Sign artifact.

Request:

{
  "artifact_id": "artifact-456",
  "key_id": "key-123"
}

GET /signing/verify/:id

Verify artifact signature.

Error Responses

All errors follow this format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Repository not found",
    "details": {}
  }
}

Common HTTP Status Codes:

  • 200: Success
  • 201: Created
  • 204: No Content
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden (including demo mode)
  • 404: Not Found
  • 409: Conflict
  • 500: Internal Server Error

Rate Limiting

API requests are rate limited:

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1612137600

Exceeded:

429 Too Many Requests
Retry-After: 60