{ "openapi": "3.0.3", "info": { "title": "XXC-APTD management", "version": "0.2.0", "description": "Unix socket: filesystem administrator authority. Administrative HTTP: local session, RBAC, exact Origin and CSRF for mutations. Public HTTP never serves these endpoints. Scoped project bearer tokens authorize only explicit publishing routes and suites. /admin is an equivalent private TCP API prefix." }, "servers": [ { "url": "https://apt.thugs.red/admin", "description": "Example path proxy. Confirm the administrative API origin with the operator; public /api is documentation only." }, { "url": "https://admin.example.invalid", "description": "Example dedicated admin origin; replace with the operator-provided value. Paths below already include /api/v1." } ], "paths": { "/api/v1/status": { "get": { "summary": "status", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/health": { "get": { "summary": "health", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer" } }, "/api/v1/packages": { "get": { "summary": "packages", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/packages/{id}": { "get": { "summary": "packages by ID", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Package" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/uploads": { "get": { "summary": "uploads", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "post": { "summary": "uploads", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Package" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "408": { "$ref": "#/components/responses/Error408" } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.debian.binary-package": { "schema": { "type": "string", "format": "binary" } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "upload" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/repository/generations": { "get": { "summary": "repository generations", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer" } }, "/api/v1/jobs": { "get": { "summary": "jobs", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "description": "Lookup is bounded to the latest 100 archive jobs. Project tokens see only jobs belonging to the same token. A completed job may later fall outside this window.", "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/jobs/{id}": { "get": { "summary": "jobs by ID", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "description": "Lookup is bounded to the latest 100 archive jobs. Project tokens see only jobs belonging to the same token. A completed job may later fall outside this window.", "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/audit": { "get": { "summary": "audit", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer" } }, "/api/v1/config": { "get": { "summary": "config", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "administrator" } }, "/api/v1/uploads/{id}/stage": { "post": { "summary": "uploads by ID stage", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageResult" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "stage" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/repository/publish": { "post": { "summary": "repository publish", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "202": { "description": "Queued; poll the returned job ID", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "409": { "$ref": "#/components/responses/Error409" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publish" } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "publish" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/repository/verify": { "post": { "summary": "repository verify", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "202": { "description": "Queued; poll the returned job ID", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "409": { "$ref": "#/components/responses/Error409" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator" } }, "/api/v1/repository/reindex": { "post": { "summary": "repository reindex", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "202": { "description": "Queued; poll the returned job ID", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "409": { "$ref": "#/components/responses/Error409" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator" } }, "/api/v1/repository/rollback": { "post": { "summary": "repository rollback", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "202": { "description": "Queued; poll the returned job ID", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "409": { "$ref": "#/components/responses/Error409" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "generation" ], "properties": { "generation": { "type": "string", "format": "uuid" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "operator" } }, "/api/v1/repository/diff": { "get": { "summary": "Review the current publication selection", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/users": { "get": { "summary": "List local users; administrator required", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "users" ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "administrator" }, "post": { "summary": "Create user; administrator required", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUser" } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "administrator" } }, "/api/v1/users/{id}": { "post": { "summary": "Change account and revoke sessions; administrator required", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "changed": { "type": "boolean" } }, "required": [ "changed" ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeUser" } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "x-minimum-role": "administrator" } }, "/api/v1/auth/challenge": { "get": { "summary": "HTTP only: create single-use login CSRF challenge", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "csrf": { "type": "string" } }, "required": [ "csrf" ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [] } }, "/api/v1/auth/login": { "post": { "summary": "HTTP only: authenticate with challenge cookie and exact Origin", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ] } }, "/api/v1/auth/session": { "get": { "summary": "HTTP only: current user, CSRF token and expiry", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/api/v1/auth/logout": { "post": { "summary": "HTTP only: revoke current session", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "logged_out": { "type": "boolean" } }, "required": [ "logged_out" ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ] } }, "/api/v1/trust/status": { "get": { "summary": "XXC Trust status", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustStatus" } } } } } } }, "/api/v1/trust/authorities": { "get": { "summary": "XXC Trust authorities", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustAuthorities" } } } } } } }, "/api/v1/trust/templates": { "get": { "summary": "XXC Trust templates", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustTemplates" } } } } } } }, "/api/v1/trust/certificates": { "get": { "summary": "XXC Trust certificates", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustCertificates" } } } } }, "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 1 }, "description": "One-based; zero is treated as one" }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 256 }, "description": "At most 256 UTF-8 bytes; control characters forbidden" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "", "active", "expiring", "expired", "revoked" ] }, "description": "Optional CA status filter" } ] } }, "/api/v1/keys": { "get": { "summary": "List remote OpenPGP keys", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenPgpKeys" } } } } }, "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 1 } }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 254 } } ] }, "post": { "summary": "Generate an OpenPGP key in XXC Trust without activation", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenPgpKey" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateOpenPgpKey" } } } }, "description": "Name/email become public key identity. Private key remains in CA. No automatic retry; inspect inventory after an ambiguous failure. Does not alter configuration or CA exchange publication." } }, "/api/v1/keys/{id}": { "get": { "summary": "Read projected remote key metadata", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenPgpKey" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } ] } }, "/api/v1/keys/{id}/public": { "get": { "summary": "Export locally validated public key bytes", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/pgp-keys": { "schema": { "type": "string", "format": "binary" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "binary", "armor" ], "default": "binary" } } ], "description": "Rejects private packets and fingerprint mismatches; accepts no secret format." } }, "/api/v1/keys/{id}/verify": { "get": { "summary": "Check public key and fingerprint consistency", "x-minimum-role": "administrator", "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "502": { "description": "Upstream authentication, TLS, network, response or rate-limit failure; safe trust_* error code", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Integration disabled or two outbound operations already running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Read-only administrator result; private fields excluded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyVerification" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } ] } }, "/api/v1/suites": { "get": { "summary": "List configured suites filtered to token authorization", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuiteList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer", "security": [ { "projectToken": [] }, { "SessionCookie": [] } ], "x-project-scope": "read" }, "parameters": [ { "name": "suite", "in": "query", "schema": { "type": "string" }, "description": "Configured suite; default repository.suite. Required when token lacks access to default." } ] }, "/api/v1/analytics": { "get": { "summary": "Private aggregate public traffic; days=7,30,90; excludes project tokens", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "viewer", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } ] } }, "/api/v1/tokens": { "get": { "summary": "Administrator token metadata or one-time credential creation", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "administrator" }, "post": { "summary": "Administrator token metadata or one-time credential creation", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "administrator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "scopes", "suites", "days" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "enum": [ "read", "upload", "stage", "publish" ] } }, "suites": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string" } }, "days": { "type": "integer", "minimum": 1, "maximum": 365 } } } } } } } }, "/api/v1/tokens/{id}/revoke": { "post": { "summary": "Administrator revocation", "responses": { "200": { "description": "Successful operation", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/Error400" }, "404": { "$ref": "#/components/responses/Error404" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "x-minimum-role": "administrator" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "components": { "securitySchemes": { "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-xxc-session", "description": "Admin HTTP interface only. When admin.external_url uses HTTPS, the cookie is __Host-xxc-session with Secure. Explicit HTTP administration uses xxc-session, independently of the public origin or proxy headers. Socket requests authenticate through filesystem permissions." }, "projectToken": { "type": "http", "scheme": "bearer", "description": "One-time project token with explicit scope and suite allowlists" } }, "schemas": { "User": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "username": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "operator", "administrator" ] }, "enabled": { "type": "boolean" }, "created": { "type": "string", "format": "date-time" } }, "required": [ "id", "username", "role", "enabled", "created" ] }, "Role": { "type": "string", "enum": [ "viewer", "operator", "administrator" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "AddUser": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "pattern": "^[a-z0-9._-]{1,64}$" }, "password": { "type": "string", "minLength": 12, "maxLength": 1024, "writeOnly": true, "description": "12..1024 UTF-8 bytes, no NUL. Never log this value." }, "role": { "type": "string", "enum": [ "viewer", "operator", "administrator" ] } }, "required": [ "username", "password", "role" ] }, "Login": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "maxLength": 64 }, "password": { "type": "string", "writeOnly": true, "maxLength": 1024 }, "csrf": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "username", "password", "csrf" ] }, "Session": { "type": "object", "additionalProperties": false, "properties": { "user": { "$ref": "#/components/schemas/User" }, "csrf": { "type": "string" }, "expires": { "type": "integer", "format": "int64" } }, "required": [ "user", "csrf", "expires" ] }, "JobAccepted": { "type": "object", "additionalProperties": false, "properties": { "job_id": { "type": "string", "format": "uuid" } }, "required": [ "job_id" ] }, "Publish": { "type": "object", "additionalProperties": false, "properties": { "review_token": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "review_token" ] }, "ChangeUser": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "password" ] }, "password": { "type": "string", "minLength": 12, "maxLength": 1024, "writeOnly": true, "description": "12..1024 UTF-8 bytes, no NUL. Never log this value." } }, "required": [ "action", "password" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "role" ] }, "role": { "type": "string", "enum": [ "viewer", "operator", "administrator" ] } }, "required": [ "action", "role" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "enable", "disable", "delete" ] } }, "required": [ "action" ] } ], "discriminator": { "propertyName": "action" } }, "Package": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "architecture": { "type": "string" }, "source": { "type": "string" }, "component": { "type": "string" }, "description": { "type": "string" }, "filename": { "type": "string" }, "sha256": { "type": "string" }, "sha512": { "type": "string" }, "uploaded": { "type": "string" }, "size": { "type": "integer", "format": "int64" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "name", "version", "architecture", "source", "component", "description", "filename", "sha256", "sha512", "uploaded", "size", "fields" ] }, "VersionChange": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "architecture": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" } }, "required": [ "name", "architecture", "before", "after" ] }, "Preview": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string" }, "current_generation": { "type": "string", "nullable": true }, "added": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "upgrades": { "type": "array", "items": { "$ref": "#/components/schemas/VersionChange" } }, "downgrades": { "type": "array", "items": { "$ref": "#/components/schemas/VersionChange" }, "description": "Older versions added; existing higher versions remain selected." }, "architectures_added": { "type": "array", "items": { "type": "string" } }, "architectures_removed": { "type": "array", "items": { "type": "string" } }, "size_delta": { "type": "integer" }, "suite": { "type": "string" } }, "required": [ "token", "current_generation", "added", "removed", "upgrades", "downgrades", "architectures_added", "architectures_removed", "size_delta", "suite" ] }, "TrustAuthority": { "type": "object", "additionalProperties": false, "required": [ "id", "parent_id", "name", "not_after", "active" ], "properties": { "id": { "type": "string" }, "parent_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "not_after": { "type": "string" }, "active": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "TrustTemplate": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "days", "eku", "algorithm", "domain_suffix" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "days": { "type": "integer", "minimum": 0 }, "eku": { "type": "string" }, "algorithm": { "type": "string" }, "domain_suffix": { "type": "string" } } }, "TrustCertificate": { "type": "object", "additionalProperties": false, "required": [ "id", "authority_id", "serial", "label", "not_before", "not_after", "status", "fingerprint", "algorithm", "eku", "template_id", "revoked_at", "sans" ], "properties": { "id": { "type": "string" }, "authority_id": { "type": "string" }, "serial": { "type": "string" }, "label": { "type": "string" }, "not_before": { "type": "string" }, "not_after": { "type": "string" }, "status": { "type": "string" }, "fingerprint": { "type": "string" }, "algorithm": { "type": "string" }, "eku": { "type": "string" }, "template_id": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "nullable": true }, "sans": { "type": "array", "items": { "type": "string" } } } }, "TrustStatus": { "type": "object", "additionalProperties": false, "required": [ "enabled", "connected" ], "properties": { "enabled": { "type": "boolean" }, "connected": { "type": "boolean" }, "authority_available": { "type": "boolean" }, "template_available": { "type": "boolean" }, "authorities": { "type": "integer", "minimum": 0 }, "templates": { "type": "integer", "minimum": 0 } } }, "TrustAuthorities": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrustAuthority" } } } }, "TrustTemplates": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrustTemplate" } } } }, "TrustCertificates": { "type": "object", "additionalProperties": false, "required": [ "items", "total", "page", "pages" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrustCertificate" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "pages": { "type": "integer", "minimum": 0 } } }, "OpenPgpKey": { "type": "object", "additionalProperties": false, "required": [ "id", "fingerprint", "label", "status", "algorithm", "capabilities", "bits", "not_after", "has_private_key" ], "properties": { "id": { "type": "string" }, "fingerprint": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "algorithm": { "type": "string" }, "capabilities": { "type": "string" }, "bits": { "type": "integer", "minimum": 0 }, "not_after": { "type": "string", "nullable": true }, "has_private_key": { "type": "boolean" } } }, "OpenPgpKeys": { "type": "object", "additionalProperties": false, "required": [ "items", "page", "pages", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OpenPgpKey" } }, "page": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "GenerateOpenPgpKey": { "type": "object", "additionalProperties": false, "required": [ "name", "email", "algorithm", "days" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 180 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "algorithm": { "type": "string", "enum": [ "Ed25519", "RSA-3072", "RSA-4096" ] }, "days": { "type": "integer", "minimum": 1, "maximum": 3650 } } }, "PublicKeyVerification": { "type": "object", "additionalProperties": false, "required": [ "public_key_valid", "fingerprint" ], "properties": { "public_key_valid": { "type": "boolean" }, "fingerprint": { "type": "string" } } }, "PackageList": { "type": "object", "additionalProperties": false, "required": [ "packages" ], "properties": { "packages": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Package" } } } }, "StageResult": { "type": "object", "additionalProperties": false, "required": [ "staged" ], "properties": { "staged": { "type": "boolean" } } }, "SuiteList": { "type": "object", "additionalProperties": false, "required": [ "default", "suites" ], "properties": { "default": { "type": "string" }, "suites": { "type": "array", "items": { "type": "string" } } } }, "Status": { "type": "object", "additionalProperties": false, "required": [ "version", "packages", "staged", "administrative_http", "generation" ], "properties": { "version": { "type": "string" }, "packages": { "type": "integer", "minimum": 0 }, "staged": { "type": "integer", "minimum": 0 }, "administrative_http": { "type": "string", "enum": [ "authentication_required", "disabled" ] }, "generation": { "type": "string", "nullable": true } } }, "Job": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "created", "finished", "message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "running", "succeeded", "failed" ] }, "created": { "type": "string", "format": "date-time" }, "finished": { "type": "string", "format": "date-time", "nullable": true }, "message": { "type": "string" } } }, "JobList": { "type": "object", "additionalProperties": false, "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Job" } } } } }, "headers": { "RequestId": { "schema": { "type": "string" }, "description": "Correlation identifier" }, "NoStore": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "responses": { "Error400": { "description": "Invalid request or application validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error404": { "description": "Unknown object", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Authentication required or generic login failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error403": { "description": "Role, Origin or CSRF rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error409": { "description": "Operation running or publication review changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error422": { "description": "Invalid JSON or form fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error429": { "description": "Login rate/concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "Error413": { "description": "Upload too large", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error408": { "description": "Upload deadline exceeded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "Origin": { "in": "header", "name": "Origin", "required": false, "description": "Required for session-authenticated HTTP mutations; must equal admin.external_url. Omit for project bearer auth or Unix socket.", "schema": { "type": "string" } }, "Csrf": { "in": "header", "name": "X-CSRF-Token", "required": false, "description": "Required for session-authenticated HTTP mutations; obtain from login/session. Omit for project bearer auth or Unix socket.", "schema": { "type": "string" } } } }, "security": [ { "SessionCookie": [] } ], "externalDocs": { "description": "Public developer guide and executable CI example", "url": "https://apt.thugs.red/api" }, "x-public-documentation": { "html": "/api", "markdown": "/api/guide.md", "openapi": "/api/openapi.json", "management-reference": "/api/reference.md" } }