{ "components": { "schemas": { "AdminRepositoryRequest": { "properties": { "visibility": { "const": "private", "type": "string" } }, "required": [ "visibility" ], "type": "object" }, "ChangePasswordRequest": { "properties": { "current": { "type": "string" }, "next": { "maxLength": 256, "minLength": 10, "type": "string" } }, "required": [ "current", "next" ], "type": "object" }, "CollaboratorRequest": { "properties": { "role": { "enum": [ "read", "write", "admin" ], "type": "string" } }, "required": [ "role" ], "type": "object" }, "CreateRepositoryRequest": { "properties": { "description": { "maxLength": 350, "type": "string" }, "id": { "description": "Optional client-generated repository ID.", "type": "string" }, "name": { "maxLength": 100, "type": "string" }, "topics": { "items": { "type": "string" }, "type": "array" }, "visibility": { "default": "private", "enum": [ "public", "private" ], "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateTokenRequest": { "properties": { "expiresInDays": { "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "maxLength": 80, "type": "string" }, "repositories": { "description": "Optional repository ID allowlist.", "items": { "type": "string" }, "maxItems": 100, "type": "array" }, "scopes": { "items": { "enum": [ "repo:read", "repo:write", "repo:admin" ], "type": "string" }, "type": "array" } }, "required": [ "name", "scopes" ], "type": "object" }, "DeleteAccountRequest": { "properties": { "password": { "type": "string" } }, "required": [ "password" ], "type": "object" }, "DeviceDecisionRequest": { "properties": { "repositories": { "items": { "type": "string" }, "maxItems": 100, "type": "array" }, "scopes": { "items": { "enum": [ "repo:read", "repo:write", "repo:admin" ], "type": "string" }, "type": "array" }, "userCode": { "type": "string" } }, "required": [ "userCode" ], "type": "object" }, "DevicePollRequest": { "properties": { "deviceCode": { "type": "string" } }, "required": [ "deviceCode" ], "type": "object" }, "DeviceStartRequest": { "properties": { "client": { "maxLength": 80, "type": "string" } }, "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "type": "object" }, "message": { "type": "string" } }, "type": "object" }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "type": "object" }, "ForkRequest": { "properties": { "name": { "maxLength": 100, "type": "string" }, "visibility": { "enum": [ "public", "private" ], "type": "string" } }, "type": "object" }, "LoginRequest": { "properties": { "password": { "type": "string" }, "username": { "description": "Username or email.", "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "NotificationReadRequest": { "properties": { "read": { "type": "boolean" } }, "required": [ "read" ], "type": "object" }, "ProfileRequest": { "properties": { "bio": { "maxLength": 500, "type": "string" }, "displayName": { "maxLength": 80, "type": "string" }, "email": { "description": "Set or clear the account email.", "format": "email", "type": [ "string", "null" ] } }, "type": "object" }, "PushRequest": { "properties": { "base": { "description": "Expected repository head; use null for an empty repository.", "type": [ "string", "null" ] }, "changes": { "items": { "properties": { "content": { "description": "New content for a create or update. Required unless delete is true.", "type": "string" }, "delete": { "default": false, "description": "Set true to delete an existing path.", "type": "boolean" }, "path": { "description": "Allowed sync path (wiki/**/*.md or athenaeum.json).", "type": "string" } }, "required": [ "path" ], "type": "object" }, "type": "array" }, "mergedFrom": { "type": "string" }, "message": { "default": "Update", "type": "string" } }, "type": "object" }, "RegisterRequest": { "properties": { "displayName": { "maxLength": 80, "type": "string" }, "email": { "format": "email", "type": "string" }, "password": { "maxLength": 256, "minLength": 10, "type": "string" }, "username": { "maxLength": 39, "minLength": 1, "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "SubscriptionRequest": { "properties": { "level": { "enum": [ "revisions" ], "type": "string" } }, "required": [ "level" ], "type": "object" }, "UpdateRepositoryRequest": { "properties": { "description": { "maxLength": 350, "type": "string" }, "name": { "maxLength": 100, "type": "string" }, "topics": { "items": { "type": "string" }, "type": "array" }, "visibility": { "enum": [ "public", "private" ], "type": "string" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "Athenaeum access token", "description": "Use an atn_ token created by POST /api/v1/user/tokens. Token scopes and optional repository restrictions are enforced by the API.", "scheme": "bearer", "type": "http" }, "sessionCookie": { "description": "Browser session cookie set by login or registration. Session-only actions require this cookie.", "in": "cookie", "name": "athenaeum_session", "type": "apiKey" } } }, "info": { "description": "The API stores account and repository metadata and the approved Athenaeum sync set: wiki/**/*.md and root athenaeum.json. Repository reads and writes enforce access on the server. Browser sessions use the athenaeum_session cookie. Programmatic clients can use scoped bearer tokens created in the signed-in account. Device authorization is available for desktop clients. See /llms.txt for the generated integration guide.", "summary": "Hosted accounts, repositories, and synchronization API.", "title": "Athenaeum API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/v1": { "get": { "description": "Returns the API and sync protocol versions, configured limits, and registration state.", "operationId": "apiInfo", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Read API capabilities", "tags": [ "System" ] } }, "/api/v1/admin/audit": { "get": { "description": "Lists operator metadata actions. Private wiki contents are not included.", "operationId": "listAdminAudit", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 100 (default 25).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Read operator audit log", "tags": [ "Administration" ] } }, "/api/v1/admin/me": { "get": { "description": "Returns the signed-in operator identity. Requires a browser session and configured operator account.", "operationId": "getAdminIdentity", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Check operator access", "tags": [ "Administration" ] } }, "/api/v1/admin/repositories": { "get": { "description": "Lists repository metadata for operators.", "operationId": "listRepositoriesAsAdmin", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 100 (default 25).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } }, { "description": "Optional owner or repository search.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Optional public or private filter.", "in": "query", "name": "visibility", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "List repositories as operator", "tags": [ "Administration" ] } }, "/api/v1/admin/repositories/{id}": { "patch": { "description": "Makes a repository private and records an operator audit event. Operators cannot publish repositories.", "operationId": "updateRepositoryAsAdmin", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRepositoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Take a repository private", "tags": [ "Administration" ] } }, "/api/v1/admin/stats": { "get": { "description": "Returns aggregate service statistics for operators.", "operationId": "getAdminStats", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Read operator statistics", "tags": [ "Administration" ] } }, "/api/v1/admin/system": { "get": { "description": "Returns service version and database metadata for operators.", "operationId": "getSystemInformation", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Read system information", "tags": [ "Administration" ] } }, "/api/v1/admin/users": { "get": { "description": "Lists account metadata for operators.", "operationId": "ListUsersAsAdmin", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 100 (default 25).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } }, { "description": "Optional username or email search.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "List users", "tags": [ "Administration" ] } }, "/api/v1/auth/device": { "post": { "description": "Creates a short-lived device code. Poll the token endpoint and ask the user to approve the displayed code.", "operationId": "startDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceStartRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Start device authorization", "tags": [ "Authentication" ] } }, "/api/v1/auth/device/approve": { "post": { "description": "Approves a pending device request and grants the requested scopes and optional repository restrictions. Requires a browser session.", "operationId": "approveDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDecisionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Approve device authorization", "tags": [ "Authentication" ] } }, "/api/v1/auth/device/deny": { "post": { "description": "Denies a pending device request. Requires a browser session.", "operationId": "denyDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDecisionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Deny device authorization", "tags": [ "Authentication" ] } }, "/api/v1/auth/device/lookup": { "get": { "description": "Returns the requesting client details for the signed-in user to review.", "operationId": "lookupDeviceAuthorization", "parameters": [ { "description": "The user code displayed by the device.", "in": "query", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Look up a device code", "tags": [ "Authentication" ] } }, "/api/v1/auth/device/token": { "post": { "description": "Polls for approval. Pending requests return a slow_down error if polled more often than the supplied interval.", "operationId": "pollDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePollRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Poll device authorization", "tags": [ "Authentication" ] } }, "/api/v1/auth/login": { "post": { "description": "Signs in with a username or email and sets the athenaeum_session cookie.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Sign in", "tags": [ "Authentication" ] } }, "/api/v1/auth/logout": { "post": { "description": "Clears the browser session cookie. The request can be used without an active session.", "operationId": "logout", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Sign out", "tags": [ "Authentication" ] } }, "/api/v1/auth/register": { "post": { "description": "Registration may be closed by the service. The response starts a browser session and sets the athenaeum_session cookie.", "operationId": "register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resource created." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Create an account", "tags": [ "Authentication" ] } }, "/api/v1/repositories": { "get": { "description": "Lists public repositories. Authenticated users can include repositories they can access with mine=true.", "operationId": "listRepositories", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 50 (default 20).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } }, { "description": "Search repository names and descriptions.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by owner username.", "in": "query", "name": "owner", "required": false, "schema": { "type": "string" } }, { "description": "Filter by topic.", "in": "query", "name": "topic", "required": false, "schema": { "type": "string" } }, { "description": "Include repositories you can access (default false).", "in": "query", "name": "mine", "required": false, "schema": { "type": "string" } }, { "description": "Sort by updated, created, name, or forks (default updated).", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Search repositories", "tags": [ "Repositories" ] }, "post": { "description": "Creates a repository owned by the authenticated user.", "operationId": "createRepository", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepositoryRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resource created." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Create a repository", "tags": [ "Repositories" ] } }, "/api/v1/repositories/{id}": { "delete": { "description": "Deletes a repository and its hosted content. Requires owner access.", "operationId": "deleteRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Delete a repository", "tags": [ "Repositories" ] }, "get": { "description": "Returns repository metadata when public or when the caller has access.", "operationId": "getRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a repository", "tags": [ "Repositories" ] }, "patch": { "description": "Updates repository metadata. Requires owner or administrator access.", "operationId": "updateRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRepositoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Update a repository", "tags": [ "Repositories" ] } }, "/api/v1/repositories/{id}/blobs/{sha}": { "get": { "description": "Returns a stored content blob by its lowercase SHA-256 digest as text/plain.", "operationId": "readBlob", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "sha identifier.", "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Successful text response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a content blob", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/collaborators": { "get": { "description": "Lists collaborators. Requires repository administrator access.", "operationId": "listCollaborators", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "List collaborators", "tags": [ "Repositories" ] } }, "/api/v1/repositories/{id}/collaborators/{username}": { "delete": { "description": "Removes a user's collaboration access.", "operationId": "removeCollaborator", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "username identifier.", "in": "path", "name": "username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Remove a collaborator", "tags": [ "Repositories" ] }, "put": { "description": "Assigns read, write, or admin access to a user.", "operationId": "setCollaborator", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "username identifier.", "in": "path", "name": "username", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaboratorRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Add or update a collaborator", "tags": [ "Repositories" ] } }, "/api/v1/repositories/{id}/compare": { "get": { "description": "Compares from and to revisions. If omitted, to defaults to the current head and from defaults to its parent.", "operationId": "compareRevisions", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Starting revision ID (optional).", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Ending revision ID (optional; defaults to head).", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Compare revisions", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/file": { "get": { "description": "Returns file metadata and Markdown content as JSON.", "operationId": "readFile", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision ID (defaults to repository head).", "in": "query", "name": "rev", "required": false, "schema": { "type": "string" } }, { "description": "Required repository-relative file path.", "in": "query", "name": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a file", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/forks": { "get": { "description": "Lists public forks of a repository.", "operationId": "listForks", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "List repository forks", "tags": [ "Repositories" ] }, "post": { "description": "Creates a fork for the authenticated user.", "operationId": "forkRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resource created." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Fork a repository", "tags": [ "Repositories" ] } }, "/api/v1/repositories/{id}/push": { "post": { "description": "Atomically applies changes if base matches the current head. Allowed paths and content are validated against the Athenaeum sync protocol.", "operationId": "pushChanges", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Push a repository revision", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/raw": { "get": { "description": "Returns the file body as text/plain.", "operationId": "readRawFile", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision ID (defaults to repository head).", "in": "query", "name": "rev", "required": false, "schema": { "type": "string" } }, { "description": "Required repository-relative file path.", "in": "query", "name": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Successful text response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read raw file content", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/revisions": { "get": { "description": "Returns newest revisions first. Use before with the last revision ID to continue paging.", "operationId": "listRevisions", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Number of revisions from 1 to 100 (default 30).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Return revisions before this revision ID.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "List repository revisions", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/revisions/{rev}": { "get": { "description": "Returns revision metadata and its manifest.", "operationId": "getRevision", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "rev identifier.", "in": "path", "name": "rev", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a revision", "tags": [ "Synchronization" ] } }, "/api/v1/repositories/{id}/star": { "delete": { "description": "Removes the signed-in user's star. Requires a browser session.", "operationId": "unstarRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Remove a repository star", "tags": [ "Engagement" ] }, "put": { "description": "Stars a repository for the signed-in user. Requires a browser session.", "operationId": "starRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Star a repository", "tags": [ "Engagement" ] } }, "/api/v1/repositories/{id}/subscription": { "delete": { "description": "Removes the signed-in user's subscription. Requires a browser session.", "operationId": "unsubscribeRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Unsubscribe from a repository", "tags": [ "Engagement" ] }, "get": { "description": "Returns the signed-in user's subscription level. Requires a browser session.", "operationId": "getSubscription", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Read repository subscription", "tags": [ "Engagement" ] }, "put": { "description": "Sets the subscription level to revisions. Requires a browser session.", "operationId": "subscribeRepository", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Subscribe to repository revisions", "tags": [ "Engagement" ] } }, "/api/v1/repositories/{id}/tree": { "get": { "description": "Lists files and directories at a revision and optional directory path.", "operationId": "readTree", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision ID (defaults to repository head).", "in": "query", "name": "rev", "required": false, "schema": { "type": "string" } }, { "description": "Directory path (default empty root).", "in": "query", "name": "path", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a repository tree", "tags": [ "Synchronization" ] } }, "/api/v1/stats": { "get": { "description": "Returns aggregate user, public repository, and revision counts.", "operationId": "publicStats", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Read public service statistics", "tags": [ "System" ] } }, "/api/v1/topics": { "get": { "description": "Returns the most used topics on public repositories.", "operationId": "listTopics", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "List repository topics", "tags": [ "Repositories" ] } }, "/api/v1/user": { "get": { "description": "Returns the authenticated user's account profile.", "operationId": "getCurrentUser", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read the current account", "tags": [ "Account" ] }, "patch": { "description": "Updates display name and bio. Requires a browser session.", "operationId": "updateCurrentUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Update the current profile", "tags": [ "Account" ] } }, "/api/v1/user/delete": { "post": { "description": "Deletes the signed-in account after password confirmation. This action is permanent.", "operationId": "deleteAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Delete the current account", "tags": [ "Account" ] } }, "/api/v1/user/notifications": { "get": { "description": "Lists notifications for the signed-in user.", "operationId": "listNotifications", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 50 (default 20).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "List notifications", "tags": [ "Engagement" ] } }, "/api/v1/user/notifications/read-all": { "post": { "description": "Marks all notifications for the signed-in user as read.", "operationId": "markAllNotificationsRead", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Mark all notifications read", "tags": [ "Engagement" ] } }, "/api/v1/user/notifications/{id}": { "patch": { "description": "Marks one notification read or unread.", "operationId": "markNotification", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Update notification read state", "tags": [ "Engagement" ] } }, "/api/v1/user/password": { "post": { "description": "Changes the signed-in account password and invalidates sessions as implemented by the service.", "operationId": "changePassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Change password", "tags": [ "Account" ] } }, "/api/v1/user/repositories": { "get": { "description": "Lists repositories owned by the current user or shared with them.", "operationId": "listMyRepositories", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "List repositories you can access", "tags": [ "Account" ] } }, "/api/v1/user/starred": { "get": { "description": "Lists repositories starred by the signed-in user.", "operationId": "listStarredRepositories", "parameters": [ { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 50 (default 20).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "List starred repositories", "tags": [ "Engagement" ] } }, "/api/v1/user/tokens": { "get": { "description": "Returns token metadata. Token secrets are shown only once when a token is created.", "operationId": "listTokens", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "List access tokens", "tags": [ "Authentication" ] }, "post": { "description": "Creates a scoped API token. Save the returned token immediately; it cannot be retrieved again.", "operationId": "createToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resource created." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Create an access token", "tags": [ "Authentication" ] } }, "/api/v1/user/tokens/{id}": { "delete": { "description": "Revokes an access token owned by the current user.", "operationId": "revokeToken", "parameters": [ { "description": "id identifier.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ { "sessionCookie": [] } ], "summary": "Revoke an access token", "tags": [ "Authentication" ] } }, "/api/v1/users/{username}": { "get": { "description": "Returns public profile fields and the count of public repositories.", "operationId": "getUser", "parameters": [ { "description": "username identifier.", "in": "path", "name": "username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Read a public user profile", "tags": [ "Users" ] } }, "/api/v1/users/{username}/repositories": { "get": { "description": "Lists public repositories owned by the named user.", "operationId": "listUserRepositories", "parameters": [ { "description": "username identifier.", "in": "path", "name": "username", "required": true, "schema": { "type": "string" } }, { "description": "One-based page number (default 1).", "in": "query", "name": "page", "required": false, "schema": { "type": "integer" } }, { "description": "Page size from 1 to 50 (default 20).", "in": "query", "name": "perPage", "required": false, "schema": { "type": "integer" } }, { "description": "Optional search text.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Sort by updated, created, name, or forks (default updated).", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "List a user's public repositories", "tags": [ "Repositories" ] } }, "/api/v1/users/{username}/repositories/{name}": { "get": { "description": "Returns a public repository. Private repositories return not found unless the request is authorized.", "operationId": "getUserRepository", "parameters": [ { "description": "username identifier.", "in": "path", "name": "username", "required": true, "schema": { "type": "string" } }, { "description": "name identifier.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookie": [] } ], "summary": "Read a repository by owner and name", "tags": [ "Repositories" ] } }, "/health": { "get": { "description": "Returns service and database readiness.", "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Successful response." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "API error response." } }, "summary": "Check API and database health", "tags": [ "System" ] } } }, "servers": [ { "description": "This API origin (production or local).", "url": "/" } ], "tags": [ { "description": "Health and service capabilities.", "name": "System" }, { "description": "Browser sessions, device authorization, and access tokens.", "name": "Authentication" }, { "description": "Current account profile and repositories.", "name": "Account" }, { "description": "Public user profiles.", "name": "Users" }, { "description": "Repository metadata, collaborators, forks, and topics.", "name": "Repositories" }, { "description": "Revisions, content reads, comparison, and atomic pushes.", "name": "Synchronization" }, { "description": "Stars, subscriptions, and notifications.", "name": "Engagement" }, { "description": "Operator-only metadata and system routes.", "name": "Administration" } ] }