# Athenaeum API

> REST API for Athenaeum accounts, repositories, and sync.

## Entry points

- Interactive reference: `/docs`
- OpenAPI 3.1 JSON: `/openapi.json` (also `/api.json`)
- API version and configured limits: `/api/v1`
- Health: `/health`
- API base URL: the current origin; endpoints are under `/api/v1`.

## Connecting a client

1. For a browser, POST JSON credentials to `/api/v1/auth/login`; the response sets the `athenaeum_session` cookie. Send requests with credentials enabled.
2. For a script or desktop client, create a scoped token while signed in at `POST /api/v1/user/tokens`, or use device authorization at `/api/v1/auth/device`. Send `Authorization: Bearer atn_…`.
3. Public profile and repository reads need no credential. Private repository access is checked by the API.
4. Push changes with `POST /api/v1/repositories/{id}/push`, including the expected `base` revision. A push is atomic and succeeds only when the base still matches. Allowed content is limited to `wiki/**/*.md` and root `athenaeum.json`.

Bearer token scopes are `repo:read`, `repo:write`, and `repo:admin`; tokens may also be restricted to repository IDs. Stars, subscriptions, notifications, profile management, token management, device approval, and operator routes require a browser session. Operator routes also require the account ID to be configured by the service. Errors use `{ error: { code, message, details? }, requestId }`.

## Operations

### GET /api/v1

Read API capabilities. Returns the API and sync protocol versions, configured limits, and registration state.
- Authentication: No authentication required.
- Success status: `200`.

### GET /api/v1/admin/audit

Read operator audit log. Lists operator metadata actions. Private wiki contents are not included.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 100 (default 25).

### GET /api/v1/admin/me

Check operator access. Returns the signed-in operator identity. Requires a browser session and configured operator account.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.

### GET /api/v1/admin/repositories

List repositories as operator. Lists repository metadata for operators.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 100 (default 25).
- `query q`: Optional owner or repository search.
- `query visibility`: Optional public or private filter.

### PATCH /api/v1/admin/repositories/{id}

Take a repository private. Makes a repository private and records an operator audit event. Operators cannot publish repositories.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- JSON body (`AdminRepositoryRequest`):
  - `visibility` (string, required).  Must be `private`.

### GET /api/v1/admin/stats

Read operator statistics. Returns aggregate service statistics for operators.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.

### GET /api/v1/admin/system

Read system information. Returns service version and database metadata for operators.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.

### GET /api/v1/admin/users

List users. Lists account metadata for operators.
- Authentication: Requires a configured operator account and browser session cookie.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 100 (default 25).
- `query q`: Optional username or email search.

### POST /api/v1/auth/device

Start device authorization. Creates a short-lived device code. Poll the token endpoint and ask the user to approve the displayed code.
- Authentication: No authentication required.
- Success status: `200`.
- JSON body (`DeviceStartRequest`):
  - `client` (string, optional). 

### POST /api/v1/auth/device/approve

Approve device authorization. Approves a pending device request and grants the requested scopes and optional repository restrictions. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- JSON body (`DeviceDecisionRequest`):
  - `repositories` (array, optional). 
  - `scopes` (array, optional). 
  - `userCode` (string, required). 

### POST /api/v1/auth/device/deny

Deny device authorization. Denies a pending device request. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- JSON body (`DeviceDecisionRequest`):
  - `repositories` (array, optional). 
  - `scopes` (array, optional). 
  - `userCode` (string, required). 

### GET /api/v1/auth/device/lookup

Look up a device code. Returns the requesting client details for the signed-in user to review.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `query code`: The user code displayed by the device.

### POST /api/v1/auth/device/token

Poll device authorization. Polls for approval. Pending requests return a slow_down error if polled more often than the supplied interval.
- Authentication: No authentication required.
- Success status: `200`.
- JSON body (`DevicePollRequest`):
  - `deviceCode` (string, required). 

### POST /api/v1/auth/login

Sign in. Signs in with a username or email and sets the athenaeum_session cookie.
- Authentication: No authentication required.
- Success status: `200`.
- JSON body (`LoginRequest`):
  - `password` (string, required). 
  - `username` (string, required). Username or email.

### POST /api/v1/auth/logout

Sign out. Clears the browser session cookie. The request can be used without an active session.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.

### POST /api/v1/auth/register

Create an account. Registration may be closed by the service. The response starts a browser session and sets the athenaeum_session cookie.
- Authentication: No authentication required.
- Success status: `201`.
- JSON body (`RegisterRequest`):
  - `displayName` (string, optional). 
  - `email` (string, optional). 
  - `password` (string, required). 
  - `username` (string, required). 

### GET /api/v1/repositories

Search repositories. Lists public repositories. Authenticated users can include repositories they can access with mine=true.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 50 (default 20).
- `query q`: Search repository names and descriptions.
- `query owner`: Filter by owner username.
- `query topic`: Filter by topic.
- `query mine`: Include repositories you can access (default false).
- `query sort`: Sort by updated, created, name, or forks (default updated).

### POST /api/v1/repositories

Create a repository. Creates a repository owned by the authenticated user.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `201`.
- JSON body (`CreateRepositoryRequest`):
  - `description` (string, optional). 
  - `id` (string, optional). Optional client-generated repository ID.
  - `name` (string, required). 
  - `topics` (array, optional). 
  - `visibility` (string, optional).  Allowed: public, private.

### DELETE /api/v1/repositories/{id}

Delete a repository. Deletes a repository and its hosted content. Requires owner access.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### GET /api/v1/repositories/{id}

Read a repository. Returns repository metadata when public or when the caller has access.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.

### PATCH /api/v1/repositories/{id}

Update a repository. Updates repository metadata. Requires owner or administrator access.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- JSON body (`UpdateRepositoryRequest`):
  - `description` (string, optional). 
  - `name` (string, optional). 
  - `topics` (array, optional). 
  - `visibility` (string, optional).  Allowed: public, private.

### GET /api/v1/repositories/{id}/blobs/{sha}

Read a content blob. Returns a stored content blob by its lowercase SHA-256 digest as text/plain.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `path sha`: sha identifier.

### GET /api/v1/repositories/{id}/collaborators

List collaborators. Lists collaborators. Requires repository administrator access.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### DELETE /api/v1/repositories/{id}/collaborators/{username}

Remove a collaborator. Removes a user's collaboration access.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- `path username`: username identifier.

### PUT /api/v1/repositories/{id}/collaborators/{username}

Add or update a collaborator. Assigns read, write, or admin access to a user.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- `path username`: username identifier.
- JSON body (`CollaboratorRequest`):
  - `role` (string, required).  Allowed: read, write, admin.

### GET /api/v1/repositories/{id}/compare

Compare revisions. Compares from and to revisions. If omitted, to defaults to the current head and from defaults to its parent.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `query from`: Starting revision ID (optional).
- `query to`: Ending revision ID (optional; defaults to head).

### GET /api/v1/repositories/{id}/file

Read a file. Returns file metadata and Markdown content as JSON.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `query rev`: Revision ID (defaults to repository head).
- `query path`: Required repository-relative file path.

### GET /api/v1/repositories/{id}/forks

List repository forks. Lists public forks of a repository.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.

### POST /api/v1/repositories/{id}/forks

Fork a repository. Creates a fork for the authenticated user.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `201`.
- `path id`: id identifier.
- JSON body (`ForkRequest`):
  - `name` (string, optional). 
  - `visibility` (string, optional).  Allowed: public, private.

### POST /api/v1/repositories/{id}/push

Push a repository revision. Atomically applies changes if base matches the current head. Allowed paths and content are validated against the Athenaeum sync protocol.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- JSON body (`PushRequest`):
  - `base` (string | null, optional). Expected repository head; use null for an empty repository.
  - `changes` (array, optional). 
  - `changes[].content` (string, optional). New content for a create or update. Required unless delete is true.
  - `changes[].delete` (boolean, optional). Set true to delete an existing path.
  - `changes[].path` (string, required). Allowed sync path (wiki/**/*.md or athenaeum.json).
  - `mergedFrom` (string, optional). 
  - `message` (string, optional). 

### GET /api/v1/repositories/{id}/raw

Read raw file content. Returns the file body as text/plain.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `query rev`: Revision ID (defaults to repository head).
- `query path`: Required repository-relative file path.

### GET /api/v1/repositories/{id}/revisions

List repository revisions. Returns newest revisions first. Use before with the last revision ID to continue paging.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `query limit`: Number of revisions from 1 to 100 (default 30).
- `query before`: Return revisions before this revision ID.

### GET /api/v1/repositories/{id}/revisions/{rev}

Read a revision. Returns revision metadata and its manifest.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `path rev`: rev identifier.

### DELETE /api/v1/repositories/{id}/star

Remove a repository star. Removes the signed-in user's star. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### PUT /api/v1/repositories/{id}/star

Star a repository. Stars a repository for the signed-in user. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### DELETE /api/v1/repositories/{id}/subscription

Unsubscribe from a repository. Removes the signed-in user's subscription. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### GET /api/v1/repositories/{id}/subscription

Read repository subscription. Returns the signed-in user's subscription level. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### PUT /api/v1/repositories/{id}/subscription

Subscribe to repository revisions. Sets the subscription level to revisions. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- JSON body (`SubscriptionRequest`):
  - `level` (string, required).  Allowed: revisions.

### GET /api/v1/repositories/{id}/tree

Read a repository tree. Lists files and directories at a revision and optional directory path.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path id`: id identifier.
- `query rev`: Revision ID (defaults to repository head).
- `query path`: Directory path (default empty root).

### GET /api/v1/stats

Read public service statistics. Returns aggregate user, public repository, and revision counts.
- Authentication: No authentication required.
- Success status: `200`.

### GET /api/v1/topics

List repository topics. Returns the most used topics on public repositories.
- Authentication: No authentication required.
- Success status: `200`.

### GET /api/v1/user

Read the current account. Returns the authenticated user's account profile.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.

### PATCH /api/v1/user

Update the current profile. Updates display name and bio. Requires a browser session.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- JSON body (`ProfileRequest`):
  - `bio` (string, optional). 
  - `displayName` (string, optional). 
  - `email` (string | null, optional). Set or clear the account email.

### POST /api/v1/user/delete

Delete the current account. Deletes the signed-in account after password confirmation. This action is permanent.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- JSON body (`DeleteAccountRequest`):
  - `password` (string, required). 

### GET /api/v1/user/notifications

List notifications. Lists notifications for the signed-in user.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 50 (default 20).

### POST /api/v1/user/notifications/read-all

Mark all notifications read. Marks all notifications for the signed-in user as read.
- Authentication: Requires a browser session cookie.
- Success status: `200`.

### PATCH /api/v1/user/notifications/{id}

Update notification read state. Marks one notification read or unread.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.
- JSON body (`NotificationReadRequest`):
  - `read` (boolean, required). 

### POST /api/v1/user/password

Change password. Changes the signed-in account password and invalidates sessions as implemented by the service.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- JSON body (`ChangePasswordRequest`):
  - `current` (string, required). 
  - `next` (string, required). 

### GET /api/v1/user/repositories

List repositories you can access. Lists repositories owned by the current user or shared with them.
- Authentication: Use a bearer token or browser session cookie.
- Success status: `200`.

### GET /api/v1/user/starred

List starred repositories. Lists repositories starred by the signed-in user.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 50 (default 20).

### GET /api/v1/user/tokens

List access tokens. Returns token metadata. Token secrets are shown only once when a token is created.
- Authentication: Requires a browser session cookie.
- Success status: `200`.

### POST /api/v1/user/tokens

Create an access token. Creates a scoped API token. Save the returned token immediately; it cannot be retrieved again.
- Authentication: Requires a browser session cookie.
- Success status: `201`.
- JSON body (`CreateTokenRequest`):
  - `expiresInDays` (integer, optional). 
  - `name` (string, required). 
  - `repositories` (array, optional). Optional repository ID allowlist.
  - `scopes` (array, required). 

### DELETE /api/v1/user/tokens/{id}

Revoke an access token. Revokes an access token owned by the current user.
- Authentication: Requires a browser session cookie.
- Success status: `200`.
- `path id`: id identifier.

### GET /api/v1/users/{username}

Read a public user profile. Returns public profile fields and the count of public repositories.
- Authentication: No authentication required.
- Success status: `200`.
- `path username`: username identifier.

### GET /api/v1/users/{username}/repositories

List a user's public repositories. Lists public repositories owned by the named user.
- Authentication: No authentication required.
- Success status: `200`.
- `path username`: username identifier.
- `query page`: One-based page number (default 1).
- `query perPage`: Page size from 1 to 50 (default 20).
- `query q`: Optional search text.
- `query sort`: Sort by updated, created, name, or forks (default updated).

### GET /api/v1/users/{username}/repositories/{name}

Read a repository by owner and name. Returns a public repository. Private repositories return not found unless the request is authorized.
- Authentication: Authentication is optional; use a session cookie or bearer token for private data.
- Success status: `200`.
- `path username`: username identifier.
- `path name`: name identifier.

### GET /health

Check API and database health. Returns service and database readiness.
- Authentication: No authentication required.
- Success status: `200`.