14 REST API

Use the REST API when you need direct HTTP integration from external systems, custom deployment tools, or platforms where invoking the CLI is not practical.

This chapter keeps API details out of the main operator workflow pages while still providing reference-quality examples for automation.

14.1 Prerequisites

Running Athene endpoint.
Valid credentials for authenticated endpoints.
HTTP client tooling such as curl.

14.2 Quick Start

Create Repository

curl -X POST "http://localhost:19191/athene/debian/main" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "distribution=bookworm&components=main&architectures=amd64"

14.3 Import and Publish Packages

Use this path when a client or automation tool needs direct upload semantics, especially for Maven layout publishing.

curl -X PUT "http://localhost:19191/r/maven/main/com/acme/demo/1.0.0/demo-1.0.0.jar" \
  -u admin:admin \
  --data-binary @target/demo-1.0.0.jar

14.4 Browse and Search Repositories

Use API browse/search endpoints when external tooling needs package visibility without invoking the CLI.

curl -X GET "http://localhost:19191/athene/debian/list-packages"
curl -X GET "http://localhost:19191/athene/debian/main/list-packages"

Athene also resolves pinned tags when browsing package and repository paths. For example, if beta is pinned for a package:

curl -X GET "http://localhost:19191/p/maven/libs-snapshots-local/com/jadaptive/jadaptive-alert-centre/beta"
curl -X GET "http://localhost:19191/r/files/jadaptive/maverick-ssh-mcp/current/ALL/ALL/maverick-ssh-mcp.mcpb"

14.5 Create a Personal Access Token

Create a PAT for the currently authenticated user:

curl -X POST "http://localhost:19191/athene/user/pat" \
  -u alice:secret \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "name=alice-ci&expiresOn=2027-01-31"

List PAT records for that user:

curl -X GET "http://localhost:19191/athene/user/pat" \
  -u alice:secret

14.6 Sync, Export, and Distribution

For automation that cannot call CLI directly, invoke sync by configured target name:

curl -X POST "http://localhost:19191/athene/debian/main/sync" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "fs=local"

This request assumes the local sync target is already configured for the repository.

14.7 Authentication

Use Authorization: Bearer <token> after CLI login when token-based API access is preferred.
Use Authorization: Basic <base64(username:password)> for direct script authentication.
Use https://localhost:19443 with -k in lab environments using self-signed certificates.

Tip

Keep API scripts intentionally small and deterministic. For multi-step package workflows, the CLI remains easier to operate and troubleshoot.

14.8 API Reference

The table below summarizes the primary endpoints used throughout this guide.

URL	Method	Parameters	Description and details
`/athene/{type}/{repository}`	`POST`	Form fields vary by repository type (for example `distribution`, `components`, `architectures` for Debian).	Create a repository.
`/athene/{type}/{repository}`	`DELETE`	Path params: `type`, `repository`.	Delete a repository.
`/athene/{type}/{repository}`	`PATCH`	Form field: `newName`.	Rename a repository.
`/athene/{type}/{repository}/copy`	`POST`	Form field: `newName`.	Copy a repository.
`/athene/{type}/{repository}/import`	`POST`	Multipart `file` and backend-specific arguments.	Import a package artifact.
`/r/maven/{repository}/{groupPath}/{artifact}/{version}/{filename}`	`PUT`	Binary payload, auth header.	Direct Maven path upload endpoint.
`/athene/{type}/list-packages`	`GET`	Path param: `type`.	List indexed packages across repositories for one backend.
`/athene/{type}/{repository}/list-packages`	`GET`	Path params: `type`, `repository`.	List indexed packages for one repository.
`/athene/{type}/{repository}/package/{selector}`	`DELETE`	Path params: `selector`, optional version variant endpoint.	Delete package by selector; ambiguity behavior is described in 13.8.1.
`/t/{type}/{repository}/{namespace...}/{package}`	`GET`	Path params: repository and package path.	Return all tags and pinned versions for one package. Requires read access to repository.
`/t/{type}/{repository}/{namespace...}/{package}/{tag}`	`GET`	Path params plus tag name.	Return package details for the version currently pinned to the tag. Returns `404` if tag is not pinned. Requires read access to repository.
`/t/{type}/{repository}/{namespace...}/{package}/{tag}`	`POST`	Form field: `version`.	Pin a tag to a specific version (create or replace). Requires write access to repository.
`/t/{type}/{repository}/{namespace...}/{package}/{tag}`	`DELETE`	Path params plus tag name.	Remove a pinned tag. Requires write access to repository.
`/athene/{type}/{repository}/sync`	`POST`	Form field: `fs=<local\|sftp\|s3>`.	Run sync/export by configured target name; see 13.8.2.
`/athene/user/pat`	`POST`	Form fields: `name` and either `expiresOn` or `neverExpires=true`.	Create personal access token for the authenticated user; see 13.8.3.
`/athene/user/pat`	`GET`	Authenticated user context.	List personal access tokens for the authenticated user.
`/athene/user/pat/{tokenId}`	`DELETE`	Path param: `tokenId`.	Delete one personal access token for the authenticated user.
`/athene/user`	`GET`	Admin auth required.	List users (password-file authenticator mode).
`/athene/user`	`POST`	Form fields: `username`, `password`.	Create user (admin operation).
`/athene/user/{username}`	`DELETE`	Path param: `username`.	Delete user (admin operation).
`/athene/user/{username}`	`POST`	Form fields: either `newPassword` or (`oldPassword`, `newPassword`) depending on flow.	Set or change user password.
`/athene/administration/reinidex`	`GET`	None.	Trigger global re-index operation.

current is a reserved immutable tag that always resolves to the newest available version by semantic version order.

14.8.1 Package Delete Ambiguity Handling

When a selector matches multiple indexed packages, Athene returns 409 Conflict with an ambiguity payload.

Use the returned matches data to retry with a more specific selector and/or explicit version.

{
  "status": "ambiguous",
  "error": "ambiguous-package",
  "message": "Package selector is ambiguous. Provide a more specific package name and/or version.",
  "matches": [
    {
      "namespace": "bookworm.main",
      "id": "some-debianpackage",
      "version": "1.2.3",
      "architecture": "AMD64",
      "path": "pool/main/s/some-debianpackage_1.2.3_amd64.deb"
    }
  ]
}

14.8.2 Sync by Named Filesystem Target

Sync/export calls use the configured filesystem target name, not a full destination URI in the request body.

curl -X POST "http://localhost:19191/athene/debian/main/sync" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "fs=local"

Valid target names are configured per repository using configuration flows (for example local, sftp, and s3).

14.8.3 Personal Access Token Lifecycle

Create a token (one-time credential returned):

curl -X POST "http://localhost:19191/athene/user/pat" \
  -u alice:secret \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "name=alice-ci&expiresOn=2027-01-31"

List token records (no token secret is returned):

curl -X GET "http://localhost:19191/athene/user/pat" \
  -u alice:secret

Delete a token by id:

curl -X DELETE "http://localhost:19191/athene/user/pat/alice%3A3b06d6f2-4f43-4f7c-95ad-1cb2c7c97f6d" \
  -u alice:secret

Next chapter: 15 Web User Interface.